Skip to content

Dependency Management with uv#

This tutorial covers how we manage Python dependencies using uv and pyproject.toml in this project.

Overview#

This project uses uv for fast, reliable Python package management. All dependencies are defined in pyproject.toml, which serves as the single source of truth.

Why uv?

  • 10-100x faster than pip
  • Consistent dependency resolution
  • Built-in virtual environment management
  • Direct support for PEP 621 (pyproject.toml)
  • Written in Rust for performance

Dependency Structure#

Dependencies are organized in pyproject.toml:

[project]
dependencies = [
    # Production dependencies (required to run the app)
    "django>=5.0",
    "mkdocs>=1.6.1",
    # ...
]

[dependency-groups]
dev = [
    # Development dependencies (testing, linting, formatting)
    "pytest>=8.4.0",
    "black>=25.1.0",
    "flake8>=7.2.0",
    # ...
]

Common Tasks#

Installing Dependencies#

# Install all dependencies (production + dev)
uv sync --all-groups

# Install production dependencies only
uv sync

# Install to a specific Python version
uv sync --python 3.12

Adding Dependencies#

# Add a production dependency
uv add <package-name>

# Add a development dependency
uv add --dev <package-name>

# Add with version constraint
uv add "django>=5.0,<6.0"

Removing Dependencies#

# Remove a production dependency
uv remove <package-name>

# Remove a development dependency
uv remove --dev <package-name>

Updating Dependencies#

# Update all dependencies
uv lock --upgrade

# Update specific package
uv lock --upgrade-package <package-name>

# Sync after updating
uv sync --all-groups

You can also sync AND upgrade using:

uv sync --upgrade

CI/CD Integration#

Our GitHub Actions workflows use uv sync to install dependencies:

- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.12'

- name: Install uv
  uses: astral-sh/setup-uv@v4

- name: Install dependencies
  run: uv sync --all-groups

Benefits:

  • Faster CI/CD builds (uv is 10-100x faster than pip)
  • Guaranteed consistency with local development
  • No need to maintain separate requirements files
  • Automatic virtual environment management

See .github/workflows/ci.yml for the complete workflow.

Generating requirements.txt Files#

Some deployment platforms or legacy tools may require requirements.txt files. Generate them from pyproject.toml:

# Generate requirements.txt (production dependencies only)
uv pip compile pyproject.toml -o requirements.txt

# Generate requirements-dev.txt (development dependencies)
uv pip compile pyproject.toml --all-extras --extra dev -o requirements-dev.txt

# Generate with specific Python version
uv pip compile pyproject.toml --python-version 3.12 -o requirements.txt

When to generate requirements.txt:

  • Deploying to platforms that don't support pyproject.toml (Heroku, some PaaS)
  • Sharing dependencies with tools that only read requirements.txt
  • Creating a snapshot of exact versions for reproducibility

Note: We don't commit requirements.txt files to version control since they can be generated from pyproject.toml. If your deployment platform requires them, generate them as part of your deployment process.

Virtual Environment Management#

Creating a Virtual Environment#

# Create virtual environment
uv venv

# Create with specific Python version
uv venv --python 3.12

# Create in custom location
uv venv .venv

Activating the Virtual Environment#

# Windows
.venv\Scripts\activate

# Unix/macOS
source .venv/bin/activate

Deactivating#

deactivate

Best Practices#

  1. Always use uv sync after pulling changes that modify pyproject.toml
  2. Don't manually edit uv.lock - it's auto-generated by uv
  3. Commit pyproject.toml and uv.lock to version control
  4. Don't commit requirements.txt unless required by deployment platform
  5. Use version constraints wisely:
  6. >= for minimum versions with flexibility
  7. ~= for compatible releases (e.g., ~=1.2.3 allows 1.2.x but not 1.3.0)
  8. Avoid pinning exact versions unless necessary for stability

Troubleshooting#

"Command not found: uv"#

Install uv:

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

"Package conflicts"#

# Clear cache and reinstall
uv cache clean
uv sync --all-groups --reinstall

"Virtual environment not found"#

# Recreate virtual environment
uv venv
uv sync --all-groups

Migration from pip/requirements.txt#

If you're migrating from a requirements.txt-based workflow:

  1. Ensure all dependencies are in pyproject.toml
  2. Remove old requirements.txt files (or keep for deployment if needed)
  3. Update CI/CD workflows to use uv sync
  4. Update documentation to reference uv commands
  5. Train team members on uv workflows

Additional Resources#