Who this guide is for

• Learners who already use virtual environments and want reliable dependency workflows
• Developers comparing pip, Poetry, PDM, uv, Hatch, Rye, and Conda-based setups
• Teams that need reproducible installs across laptops, CI, and production

What you’ll learn

• The role of package managers and lock files in Python projects
• When to use pip + requirements.txt versus modern pyproject.toml workflows
• The strengths of Poetry, PDM, uv, Hatch, Rye, and Conda/Miniconda
• How PyPI and dependency resolution fit into real project lifecycle
• A practical decision guide for choosing tools based on project context

Why this topic matters

As soon as your project uses third-party libraries, package management becomes critical. Poor dependency management causes “works on my machine” bugs, broken builds, and painful onboarding for new contributors.

Modern Python tooling gives you many options, which is powerful but confusing. This guide helps you choose a setup intentionally so your environment stays reproducible, upgrades are safer, and collaboration is smoother.

Core concepts

Package manager roles and core files

Package managers solve three main problems:

• Install dependencies
• Resolve compatible versions
• Reproduce environments later

Common file patterns:

• requirements.txt: plain dependency list (often with pinned versions)
• pyproject.toml: modern project metadata + dependencies
• Lock files (poetry.lock, pdm.lock, uv.lock): exact resolved dependency graph

PyPI (Python Package Index) is the default public package registry used by most Python tools. When you run pip install requests, the package is normally fetched from PyPI unless you configure another index.

python -m pip index versions requests

This command helps you inspect available versions published on PyPI.

Minimal requirements.txt example:

requests==2.32.3
pandas==2.2.3

Minimal pyproject.toml fragment example:

[project]
name = "my-app"
version = "0.1.0"
dependencies = [
	"requests>=2.32.0",
	"pandas>=2.2.0"
]

Tool ecosystem overview

Each tool optimizes for slightly different workflows:

• pip: universal baseline, simple and widely available
• Poetry: dependency management + packaging with lock-first workflow
• PDM: PEP-friendly modern workflow centered on pyproject.toml
• uv: very fast dependency installer/resolver and environment workflow
• Hatch: environment and project automation focus
• Rye: opinionated project workflow (ecosystem status can evolve)
• Conda/Miniconda: strong for scientific stacks and non-Python binary dependencies

No single tool is always best. Choose based on team needs, CI constraints, and domain.

Choosing the right strategy

Use this practical shortcut:

• Solo script or small automation -> venv + pip + requirements.txt
• Standard app/service with packaging needs -> Poetry or PDM
• Performance-sensitive installs / modern workflows -> consider uv
• Data science stack with compiled dependencies -> Conda/Miniconda often easier

Whichever you choose, keep these rules:

• Pin or lock dependencies
• Commit dependency files to version control
• Use CI to verify reproducible install

Decision flow (quick text version):

Do you need scientific/non-Python binaries?
	├─ Yes -> Conda/Miniconda
	└─ No
			├─ Need minimal/simple workflow? -> pip + requirements.txt
			├─ Need lock-first project management? -> Poetry or PDM
			└─ Need very fast installs/resolution? -> uv

Step-by-step walkthrough

Step 1 — Start with a baseline pip workflow

Create and activate a virtual environment first, then install packages.

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install requests pandas
python -m pip freeze > requirements.txt

On Windows PowerShell, activate with:

.venvScriptsActivate.ps1

This baseline works everywhere and is a strong foundation.

Step 2 — Try a pyproject.toml-first workflow

If you want modern metadata + locking, test one tool (for example Poetry).

poetry init
poetry add requests pandas
poetry install

You will get:

• pyproject.toml for project metadata/dependency declarations
• poetry.lock for reproducible installs

Equivalent flows exist in PDM and uv ecosystems.

Step 3 — Validate reproducibility from a clean environment

Delete and recreate your environment, then reinstall from dependency files.

For pip flow:

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

For Poetry flow:

poetry install

If both work repeatedly on a fresh setup, your dependency management is healthy.

Practical examples

Example 1 — Compare install workflows quickly

Use this side-by-side to understand output artifacts.

pip style:

python -m pip install fastapi uvicorn
python -m pip freeze > requirements.txt

Expected artifact:

requirements.txt

Poetry style:

poetry add fastapi uvicorn

Expected artifacts:

pyproject.toml
poetry.lock

PDM style:

pdm add fastapi uvicorn

Expected artifacts:

pyproject.toml
pdm.lock

Both are valid. The key is consistency within one project.

Example 2 — Minimal decision flow in practice

Imagine three project scenarios:

Scenario A: single automation script -> pip + requirements.txt
Scenario B: API service with team contributors -> Poetry/PDM + lock file
Scenario C: ML environment with heavy compiled packages -> Conda

Expected result:

• Faster onboarding because tooling is explicit
• Fewer version conflicts across machines
• Cleaner CI pipelines with deterministic installs

Common mistakes and how to avoid them

• Mixing multiple package managers in one project without rules -> Standardize one primary workflow per repository.
• Not committing lock/dependency files -> Commit requirements.txt or lock file so teammates can reproduce installs.
• Using unpinned broad versions carelessly -> Pin exact versions or maintain controlled version ranges.
• Installing globally instead of inside virtual environments -> Always activate project .venv before installs.
• Switching tools mid-project without migration plan -> Document migration steps and verify CI before merging.

Quick practice

• Create a sample project using pip + requirements.txt, then rebuild it from scratch on a fresh virtual environment.
• Create a second sample project using Poetry or PDM and compare generated files.
• Write a short decision note: which tool you will use for your next project and why.

Key takeaways

• Dependency management is a core engineering practice, not just setup work.
• pip remains a solid baseline; modern tools add stronger project metadata and locking workflows.
• pyproject.toml is now central in modern Python project configuration.
• Reproducibility depends on clear files, consistent tool choice, and repeatable clean installs.

Next step

Continue to Common & Useful Python Packages. In the next guide, you will explore practical libraries from the standard library and third-party ecosystem for HTTP, paths, and data workflows.