Dependency Manager

Manage Python project dependencies with UV, pip-tools, or requirements.txt.

Quick Start

Choose UV for new projects (fast, modern), pip-tools for existing pip workflows, or requirements.txt for simple projects.

Instructions

Choosing a Tool

UV - Fast, modern Python package manager (recommended):

•Extremely fast dependency resolution (10-100x faster than pip)
•Automatic virtual environment management
•Drop-in replacement for pip and pip-tools
•Lock file support with uv.lock
•Best for: All projects, especially new ones

pip-tools - Lightweight, pip-compatible workflow:

•Generates lock files from requirements.in
•Works with existing pip workflows
•Minimal changes to project structure
•Best for: Existing projects, CI/CD with pip, gradual adoption

requirements.txt - Simple, universal:

•Direct pip install
•No additional tools
•No lock file (unless manually maintained)
•Best for: Simple scripts, minimal dependencies, quick prototypes

UV Setup (Recommended)

Install UV:

bash

curl -LsSf https://astral.sh/uv/install.sh | sh
# Or with pip
pip install uv

Initialize new project:

bash

uv init my-project
cd my-project

Add dependencies:

bash

# Runtime dependency
uv add requests

# Development dependency
uv add --dev pytest

# With version constraint
uv add "requests>=2.28.0,<3.0.0"

Install dependencies:

bash

uv sync

Update dependencies:

bash

# Update all
uv lock --upgrade

# Update specific package
uv lock --upgrade-package requests

Remove dependencies:

bash

uv remove requests

Show dependency tree:

bash

uv tree

Export to requirements.txt:

bash

uv pip compile pyproject.toml -o requirements.txt

Run commands in virtual environment:

bash

uv run python script.py
uv run pytest

pip-tools Setup

Install pip-tools:

bash

pip install pip-tools

Create requirements.in:

code

# requirements.in
requests>=2.28.0
flask>=2.0.0

Create requirements-dev.in:

code

# requirements-dev.in
-c requirements.txt  # Constrain to production versions
pytest>=7.0.0
black>=23.0.0
mypy>=1.0.0

Compile lock files:

bash

# Compile production dependencies
pip-compile requirements.in

# Compile dev dependencies
pip-compile requirements-dev.in

This generates requirements.txt and requirements-dev.txt with pinned versions.

Install dependencies:

bash

pip-sync requirements.txt requirements-dev.txt

Update dependencies:

bash

# Update all
pip-compile --upgrade requirements.in

# Update specific package
pip-compile --upgrade-package requests requirements.in

Add new dependency:

•Add to requirements.in
•Run pip-compile requirements.in
•Run pip-sync requirements.txt

requirements.txt Workflow

Create requirements.txt:

bash

pip freeze > requirements.txt

Install dependencies:

bash

pip install -r requirements.txt

Separate dev dependencies:

Create requirements-dev.txt:

code

-r requirements.txt
pytest>=7.0.0
black>=23.0.0

Install with:

bash

pip install -r requirements-dev.txt

Version Constraints

UV/PEP 621 syntax (pyproject.toml):

toml

[project]
dependencies = [
    "requests>=2.28.0,<3.0.0",  # Range
    "flask~=2.0.0",              # Compatible release
    "django>=3.2,<4.0",          # Range
    "numpy==1.24.0",             # Exact version
]

pip syntax (requirements.in or requirements.txt):

code

requests>=2.28.0,<3.0.0
flask~=2.0.0
django>=3.2,<4.0
numpy==1.24.0
pandas

Constraint operators:

•==: Exact version
•>=, <=: Minimum/maximum version
•~=: Compatible release (patch updates)
•,: Combine constraints (AND)

Dependency Groups

UV/PEP 621 groups:

toml

[project.optional-dependencies]
dev = ["pytest>=7.0.0", "black>=23.0.0"]
docs = ["sphinx>=5.0.0"]
test = ["coverage>=7.0.0"]

Install specific groups:

bash

uv sync --extra dev
uv sync --extra docs
uv sync --all-extras

pip-tools approach:

Create separate .in files:

•requirements.in - Production
•requirements-dev.in - Development
•requirements-test.in - Testing
•requirements-docs.in - Documentation

Resolving Conflicts

With UV:

•

Check conflict:

bash

uv add package-name
# UV will show conflict if it exists

•

Update constraints in pyproject.toml:

toml

[project]
dependencies = [
    "package-a>=2.0.0",  # Relax constraint
    "package-b>=3.0.0",
]

•
Force resolution:
bash
```
uv lock
uv sync
```

With pip-tools:

•

Check conflict:

bash

pip-compile requirements.in
# Will show resolution errors

•

Adjust constraints in requirements.in:

code

package-a>=2.0.0  # Relax constraint
package-b>=3.0.0

•
Recompile:
bash
```
pip-compile requirements.in
```

Common conflict patterns:

•
Transitive dependency conflict: Two packages require incompatible versions of a third package
- •Solution: Update one or both packages, or relax constraints
•
Python version conflict: Package requires newer Python than project supports
- •Solution: Upgrade Python version or find alternative package
•
Platform-specific conflict: Package not available on current platform
- •Solution: Use platform markers or optional dependencies

Platform-Specific Dependencies

UV/PEP 621:

toml

[project]
dependencies = [
    "pywin32>=305; sys_platform == 'win32'",
    "python-daemon>=2.3; sys_platform == 'linux'",
]

pip:

code

pywin32>=305; sys_platform == 'win32'
python-daemon>=2.3; sys_platform == 'linux'

Optional Dependencies

UV/PEP 621:

toml

[project.optional-dependencies]
aws = ["boto3>=1.26.0"]
all = ["boto3>=1.26.0"]  # Include all optional deps

Install with:

bash

uv sync --extra aws
uv pip install package-name[aws]

Virtual Environments

UV (automatic):

bash

# UV creates and manages venv automatically
uv sync
uv run python script.py
source .venv/bin/activate  # Manual activation if needed

pip-tools (manual):

bash

# Create venv
python -m venv venv

# Activate
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Install
pip-sync requirements.txt

requirements.txt (manual):

bash

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

CI/CD Integration

UV in CI (recommended):

yaml

# .github/workflows/test.yml
- name: Install UV
  run: curl -LsSf https://astral.sh/uv/install.sh | sh

- name: Install dependencies
  run: uv sync

- name: Run tests
  run: uv run pytest

pip-tools in CI:

yaml

- name: Install dependencies
  run: |
    pip install pip-tools
    pip-sync requirements.txt requirements-dev.txt

- name: Run tests
  run: pytest

requirements.txt in CI:

yaml

- name: Install dependencies
  run: pip install -r requirements.txt

- name: Run tests
  run: pytest

Migration Strategies

From requirements.txt to UV:

•
Initialize UV project:
bash
```
uv init --no-readme
```

•

Import dependencies:

bash

# Add each dependency from requirements.txt
cat requirements.txt | grep -v "^#" | xargs -I {} uv add {}

•
Separate dev dependencies:
bash
```
uv add --dev pytest black mypy
```
•
Test:
bash
```
uv sync
uv run pytest
```

From requirements.txt to pip-tools:

•
Rename requirements.txt:
bash
```
mv requirements.txt requirements.in
```
•
Compile lock file:
bash
```
pip-compile requirements.in
```

•

Create dev requirements:

bash

echo "-c requirements.txt" > requirements-dev.in
echo "pytest" >> requirements-dev.in
pip-compile requirements-dev.in

•

Test:

bash

pip-sync requirements.txt requirements-dev.txt

From pip-tools to UV:

•
Create pyproject.toml:
bash
```
uv init --no-readme
```

•

Import from requirements.in:

bash

cat requirements.in | grep -v "^#" | grep -v "^-" | xargs -I {} uv add {}

•
Test:
bash
```
uv sync
```

Common Patterns

Monorepo with Shared Dependencies

UV workspace:

toml

# Root pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]

# packages/package1/pyproject.toml
[project]
name = "package1"
dependencies = ["requests>=2.28.0"]

# packages/package2/pyproject.toml
[project]
name = "package2"
dependencies = ["requests>=2.28.0"]

pip-tools approach:

code

# shared-requirements.in
requests>=2.28.0

# package1/requirements.in
-c ../shared-requirements.txt
flask>=2.0.0

# package2/requirements.in
-c ../shared-requirements.txt
django>=4.0.0

Lock File Best Practices

Commit lock files:

•uv.lock - Always commit
•requirements.txt (from pip-compile) - Always commit
•requirements.txt (from pip freeze) - Consider committing

Update regularly:

bash

# UV
uv lock --upgrade

# pip-tools
pip-compile --upgrade requirements.in

Verify after updates:

bash

# Run tests
uv run pytest

# Check for security issues
pip-audit

Troubleshooting

UV lock takes too long:

•UV is typically very fast; if slow, check for network issues
•Use uv lock --offline to use cached packages
•Check for circular dependencies

pip-compile fails with conflict:

•Relax version constraints in requirements.in
•Use pip-compile --resolver=backtracking for better resolution
•Check for incompatible transitive dependencies

Dependencies not found:

•Verify package name (check PyPI)
•Check Python version compatibility
•Ensure correct index URL (for private packages)
•With UV: uv pip install --index-url https://custom-index.com package

Virtual environment issues:

•Delete and recreate: rm -rf .venv && uv sync
•Check Python version matches project requirements
•UV automatically manages virtual environments

Outdated dependencies:

•Check with: uv tree --outdated or pip list --outdated
•Update carefully, test after each major update
•Use uv lock --upgrade --dry-run to preview changes