Gondulf/docs/decisions/ADR-002-uv-environment-management.md

ADR-002: Use uv for Python Virtual Environment Management

Date: 2025-11-20

Status

Accepted

Context

The IndieAuth server project requires a Python virtual environment management tool that aligns with our core value of simplicity while providing modern development experience. Traditional tools like venv, virtualenv, and poetry each have their trade-offs in terms of speed, complexity, and feature set.

uv is a modern Python package and project manager written in Rust, created by the Astral team (makers of Ruff). It offers exceptional performance while maintaining compatibility with standard Python packaging tools and workflows.

Decision

We will use uv as the primary tool for Python virtual environment management and dependency installation in the IndieAuth server project.

What is uv?

uv is an extremely fast Python package installer and resolver, written in Rust. Key characteristics:

• 10-100x faster than pip and pip-tools for dependency resolution and installation
• Drop-in replacement for pip, pip-tools, and virtualenv
• Standards-compliant - works with standard requirements.txt and pyproject.toml files
• Simple - focuses on doing package management well without unnecessary complexity
• Actively maintained by the Astral team with frequent updates

Direct Execution Model

We will use uv's direct execution commands (uv run, uv pip) rather than traditional virtual environment activation:

• Instead of: source .venv/bin/activate then python script.py
• We use: uv run python script.py
• Instead of: Activating environment then pip install package
• We use: uv pip install package

This approach eliminates activation state confusion, works consistently across all shells and platforms, and makes CI/CD pipelines simpler.

Consequences

Positive Consequences

1. Developer Experience: Dramatically faster dependency installation speeds up development cycles
2. Simplicity: No new concepts to learn - uses standard Python packaging conventions
3. No Activation Confusion: Direct execution model eliminates "which environment am I in?" questions
4. Shell Agnostic: Works identically across bash, zsh, fish, PowerShell, etc.
5. CI/CD Friendly: Commands are explicit and don't require activation scripts
6. Compatibility: Works with existing Python packaging ecosystem (PyPI, requirements.txt, etc.)
7. Reproducibility: Built-in support for lockfiles ensures consistent environments
8. Modern Tooling: Aligns with other modern Python tools like Ruff (linting) from the same team
9. No Runtime Dependency: uv is only needed for development; production deployments use standard Python

Negative Consequences

1. Newer Tool: Less community knowledge compared to pip/venv (mitigated by excellent documentation)
2. Additional Installation: Developers need to install uv separately (simple one-line installation)
3. Rust Dependency: Requires Rust toolchain for building from source (pre-built binaries available)

Why This Aligns with Project Values

• Simplicity: uv provides a simpler, faster workflow without adding complexity
• Standards Compliance: Uses standard Python packaging formats
• Maintainability: Faster feedback loops improve developer productivity
• Modern Best Practices: Represents current best practices in Python tooling

Implementation Notes

• uv will manage virtual environments in the project root as .venv/
• Dependencies will be specified in pyproject.toml with a uv.lock file for reproducibility
• All development commands will use direct execution (uv run, uv pip) without activation
• The project will maintain compatibility with standard pip installation for production deployments
• Documentation in /docs/standards/development-environment.md provides comprehensive usage patterns
• IDE configuration will point directly to .venv/bin/python for interpreter selection