Dependency Manager

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,=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:

1. Add to requirements.in
2. Run pip-compile requirements.in
3. 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.2,=2.28.0,=3.2,=`, `=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:

1. Check conflict:

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

1. Update constraints in pyproject.toml:

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

1. Force resolution:

``bash uv lock uv sync ``

With pip-tools:

1. Check conflict:

``bash pip-compile requirements.in # Will show resolution errors ``

1. Adjust constraints in requirements.in:

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

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

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

1. Initialize UV project:

``bash uv init --no-readme ``

1. Import dependencies:

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

1. Separate dev dependencies:

``bash uv add --dev pytest black mypy ``

1. Test:

``bash uv sync uv run pytest ``

From requirements.txt to pip-tools:

1. Rename requirements.txt:

``bash mv requirements.txt requirements.in ``

1. Compile lock file:

``bash pip-compile requirements.in ``

1. Create dev requirements:

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

1. Test:

``bash pip-sync requirements.txt requirements-dev.txt ``

From pip-tools to UV:

1. Create pyproject.toml:

``bash uv init --no-readme ``

1. Import from requirements.in:

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

1. Test:

``bash 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: armanzeroeight
• Source: armanzeroeight/fastagent-plugins
• License: MIT

Install and usage instructions live in the source repository linked above.