name	dependency-manager
description	Manage Python dependencies using UV, pip-tools, or requirements.txt. Use when setting up dependency management, resolving conflicts, or choosing between UV, pip-tools, and requirements.txt workflows.

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:

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

Initialize new project:

uv init my-project
cd my-project

Add dependencies:

# 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:

uv sync

Update dependencies:

# Update all
uv lock --upgrade

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

Remove dependencies:

uv remove requests

Show dependency tree:

uv tree

Export to requirements.txt:

uv pip compile pyproject.toml -o requirements.txt

Run commands in virtual environment:

uv run python script.py
uv run pytest

pip-tools Setup

Install pip-tools:

pip install pip-tools

Create requirements.in:

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

Create requirements-dev.in:

# 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:

# 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:

pip-sync requirements.txt requirements-dev.txt

Update dependencies:

# 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:

pip freeze > requirements.txt

Install dependencies:

pip install -r requirements.txt

Separate dev dependencies:

Create requirements-dev.txt:

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

Install with:

pip install -r requirements-dev.txt

Version Constraints

UV/PEP 621 syntax (pyproject.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):

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:

[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:

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:

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

Update constraints in pyproject.toml:

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

Force resolution:
```
uv lock
uv sync
```

With pip-tools:

Check conflict:

pip-compile requirements.in
# Will show resolution errors

Adjust constraints in requirements.in:

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

Recompile:
```
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:

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

pip:

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

Optional Dependencies

UV/PEP 621:

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

Install with:

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

Virtual Environments

UV (automatic):

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

pip-tools (manual):

# 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):

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

CI/CD Integration

UV in CI (recommended):

# .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:

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

- name: Run tests
  run: pytest

requirements.txt in CI:

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

- name: Run tests
  run: pytest

Migration Strategies

From requirements.txt to UV:

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

Import dependencies:

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

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

From requirements.txt to pip-tools:

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

Create dev requirements:

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

Test:

pip-sync requirements.txt requirements-dev.txt

From pip-tools to UV:

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

Import from requirements.in:

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

Test:
```
uv sync
```

Common Patterns

Monorepo with Shared Dependencies

UV workspace:

# 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:

# 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:

# UV
uv lock --upgrade

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

Verify after updates:

# 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

dependency-manager

Install Skill

SKILL.md

Dependency Manager

Quick Start

Instructions

Choosing a Tool

UV Setup (Recommended)

pip-tools Setup

requirements.txt Workflow

Version Constraints

Dependency Groups

Resolving Conflicts

Platform-Specific Dependencies

Optional Dependencies

Virtual Environments

CI/CD Integration

Migration Strategies

Common Patterns

Monorepo with Shared Dependencies

Lock File Best Practices

Troubleshooting