Package Management with uv

Overview

This project uses uv as the primary package manager for Python dependencies. uv is a fast, reliable Python package and project manager written in Rust.

Why uv?

• Speed: 10-100x faster than pip and pip-tools
• Reliability: Built-in resolver prevents dependency conflicts
• Simplicity: Single tool for package and project management
• Compatibility: Drop-in replacement for pip commands
• Lock files: Automatic dependency locking for reproducible builds

Installation

Install uv

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

# Using pip (fallback)
pip install uv

# Verify installation
uv --version

Basic Usage

Installing Dependencies

# Install project with all dependencies
uv sync

# Install including dev dependencies
uv sync --dev

# Install specific package
uv add package-name

# Install dev dependency
uv add --dev pytest-cov

# Install from requirements file
uv pip install -r requirements.txt

Running Commands

# Run command in project environment
uv run python script.py

# Run pytest
uv run pytest

# Run with coverage
uv run pytest --cov=src/{{package_name}}

# Run any command
uv run make test

Managing Dependencies

# Add a new dependency
uv add numpy

# Add dev dependency
uv add --dev pytest-benchmark

# Remove dependency
uv remove package-name

# Update dependencies
uv sync --upgrade

# Show installed packages
uv pip list

Project Configuration

pyproject.toml

The project uses pyproject.toml for dependency management:

[project]
dependencies = [
    "pydantic>=2.0.0",
    "python-dotenv>=1.0.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=8.0.0",
    "pytest-asyncio>=0.24.0",
    "pytest-cov>=6.0.0",
    "mypy>=1.0.0",
    "ruff>=0.8.0",
]

Lock File

uv.lock ensures reproducible installations:

• Automatically generated and updated
• Should be committed to version control
• Ensures all developers use same dependency versions

Common Commands Reference

Development Workflow

# Initial setup
git clone <repo>
cd {{project-name}}
uv sync --dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/{{package_name}}

# Run linting
uv run ruff check .

# Run type checking
uv run mypy src/

# Format code
uv run ruff format .

Package Management

# Add production dependency
uv add fastapi

# Add dev dependency
uv add --dev black

# Add with version constraint
uv add "pandas>=2.0.0"

# Remove package
uv remove pandas

# Update all dependencies
uv sync --upgrade

# Update specific package
uv add --upgrade numpy

Environment Management

# Create virtual environment (automatic with uv sync)
uv venv

# Activate environment (usually not needed with uv run)
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Show environment info
uv pip list
uv pip show package-name

Makefile Integration

The project includes a comprehensive Makefile configured to use uv for all operations.

📚 See the complete Makefile template: python/templates/Makefile

Common Make Targets

# Installation
make install        # Install production dependencies
make dev-install    # Install all dependencies including dev
make upgrade        # Upgrade all dependencies

# Testing
make test          # Run all tests
make test-cov      # Run tests with coverage report
make test-watch    # Run tests in watch mode

# Code Quality
make lint          # Run all linting checks
make lint-fix      # Fix auto-fixable issues
make format        # Format code with ruff and black
make typecheck     # Run type checking with mypy

# Development
make run           # Run the main application
make shell         # Open interactive Python shell
make clean         # Clean build artifacts

# Quality Assurance
make qa            # Run all quality checks
make ready         # Prepare code for commit

The Makefile template includes many more targets for CI/CD, documentation, dependency management, and more. See the full template for complete functionality.

CI/CD Integration

GitHub Actions

- name: Install uv
  uses: astral-sh/setup-uv@v3
  
- name: Install dependencies
  run: uv sync --dev

- name: Run tests
  run: uv run pytest --cov=src/{{package_name}}

Migration from pip

For Developers

Replace pip commands with uv equivalents:

pip command	uv command
pip install package	uv add package
pip install -e .	uv sync
pip install -r requirements.txt	uv pip install -r requirements.txt
pip uninstall package	uv remove package
pip list	uv pip list
pip freeze	uv pip freeze
python script.py	uv run python script.py
pytest	uv run pytest

For Scripts

Update automation scripts:

# Old (pip)
pip install -e ".[dev]"
pytest

# New (uv)
uv sync --dev
uv run pytest

Troubleshooting

Common Issues

uv command not found

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

# Add to PATH
export PATH="$HOME/.cargo/bin:$PATH"

Dependency conflicts

# Clear cache and reinstall
uv cache clean
rm -rf .venv uv.lock
uv sync --dev

Wrong Python version

# Specify Python version
uv venv --python 3.11
uv sync

Import errors after install

# Ensure using uv run
uv run python  # Not just 'python'
uv run pytest  # Not just 'pytest'

Best Practices

DO's

✅ Always use uv run to execute commands
✅ Commit uv.lock to version control
✅ Use uv add instead of editing pyproject.toml manually
✅ Keep dev dependencies separate with --dev flag
✅ Use uv sync after pulling changes

DON'Ts

❌ Don't use pip alongside uv in the same project
❌ Don't manually activate venv when using uv run
❌ Don't ignore uv.lock in git
❌ Don't edit uv.lock manually
❌ Don't mix pip and uv commands

Advanced Usage

Custom Package Index

# Add custom index
uv add --index-url https://custom.pypi.org/simple/ package

# Use extra index
uv add --extra-index-url https://extra.pypi.org/simple/ package

Platform-specific Dependencies

[tool.uv]
dependencies = [
    "windows-only-package ; sys_platform == 'win32'",
    "unix-only-package ; sys_platform != 'win32'",
]

Workspace Management

# For monorepo with multiple packages
uv sync --workspace

Related Documentation

• uv Documentation
• pyproject.toml Specification
• Python Packaging Guide
• Project README

Template Metadata

• Repository: vibe-coding-templates
• Path: python/docs/PACKAGE_MANAGEMENT.md
• Version: 1.0.0
• Date: 2025-01-19
• Author: chrishayuk