Skip to main content
Entirius
AI platform for e-commerce
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

ADR-007: UV Python Package Manager

Status

Status: Accepted
Date: 2025-07-02
Authors: Piotr Brzozowski
Reviewers: Piotr Brzozowski

Decision

Adopt UV as the primary Python package manager for all new projects in the Entirius organization. UV provides 10-100x faster dependency installation with native pyproject.toml support and modern Python packaging standards compliance.

Quick Reference

Installation:

# Install UV (Linux/Mac)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install UV (Windows)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Essential Commands:

# Create virtual environment and install dependencies
uv venv
uv pip install -r requirements.txt

# Add new packages
uv add package-name
uv add --dev package-name  # development dependencies

# Sync dependencies (recommended)
uv pip sync requirements.txt

# Activate virtual environment
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate  # Windows

Migration Checklist:

  • Replace pip with uv for all installations
  • Use pyproject.toml instead of requirements.txt for new projects
  • Update CI/CD pipelines to use UV
  • Install UV on all development machines

Context

The Entirius project is a modern e-commerce AI platform designed from the ground up with contemporary development practices. As a modern project, we adopt current Python packaging standards using pyproject.toml and modern dependency management. Traditional approaches with legacy requirements.txt files and pip/venv have several limitations:

  • Slow dependency resolution and installation times
  • Dependency conflict resolution challenges
  • Multiple tool ecosystem (pip, venv, pipenv, poetry) creating complexity
  • Lack of modern dependency locking mechanisms
  • Poor performance with large dependency trees
  • Limited cross-platform consistency
  • Outdated requirements.txt format without rich metadata support

As a modern project built with performance and developer experience in mind, Entirius requires a state-of-the-art Python package management solution that can:

  • Deliver exceptional development workflow speed from day one
  • Provide superior dependency resolution capabilities
  • Support modern Python packaging standards (PEP 517/518)
  • Use pyproject.toml for unified project configuration
  • Minimize complexity in development environment setup
  • Support efficient local development and CI/CD pipelines

Considered Options

Option 1: Adopt traditional pip + venv + requirements.txt

  • Description: Use the legacy approach with pip, venv, and requirements.txt files for dependency management
  • Pros:
    • Well-established and widely known
    • Part of Python standard library
    • Maximum compatibility
    • No learning curve for team
  • Cons:
    • Slow dependency resolution and installation
    • Poor dependency conflict resolution
    • Manual dependency locking process
    • Multiple tools to manage
    • Outdated requirements.txt format lacks metadata
    • No built-in support for modern packaging standards
  • Impact on system: Would require accepting slower development workflows and legacy file formats

Option 2: Poetry

  • Description: Adopt Poetry as the Python package and dependency manager with pyproject.toml
  • Pros:
    • Integrated dependency management and virtual environments
    • Automatic dependency locking (poetry.lock)
    • Uses modern pyproject.toml standard
    • Good dependency resolution
    • Popular in Python community
  • Cons:
    • Still relatively slow compared to modern alternatives
    • Complex pyproject.toml configuration for advanced use cases
    • Occasional dependency resolution issues
    • Heavier runtime requirements
  • Impact on system: Establishes modern pyproject.toml-based workflow but with slower performance

Option 3: UV

  • Description: Adopt Astral’s UV as the primary Python package manager with pyproject.toml
  • Pros:
    • Extremely fast (10-100x faster than pip)
    • Native pyproject.toml support (PEP 517/518)
    • Written in Rust for performance
    • Modern dependency management with uv.lock
    • Unified tool for multiple package management tasks
    • Superior dependency resolution
    • Active development by Astral (creators of Ruff)
    • First-class support for modern Python packaging standards
  • Cons:
    • Relatively new tool (less mature ecosystem)
    • Team learning curve
    • Potential compatibility issues with edge cases
  • Impact on system: Establishes modern pyproject.toml-based workflow with exceptional performance from project inception

Rationale

Chosen option: UV Python Package Manager

Key decision factors:

  • Performance: 10-100x faster installation times will dramatically improve developer productivity
  • Modern standards: Native support for pyproject.toml and modern Python packaging (PEP 517/518)
  • Unified tooling: Single tool replacing pip, venv, pip-tools with superior performance
  • Future-proof: Backed by Astral, the company behind Ruff, showing commitment to Python tooling excellence
  • Modern foundation: Establishes cutting-edge development practices with pyproject.toml from project inception
  • Advanced dependency management: Modern uv.lock files providing deterministic builds
  • CI/CD benefits: Faster builds and deployments with modern dependency resolution
  • Risk analysis: Backed by reputable company (Astral) with strong commitment to Python tooling excellence
  • Impact on business goals: Dramatically improved developer productivity and reduced build times
  • Compatibility with existing architecture: Perfect alignment with modern Python packaging standards and pyproject.toml adoption
  • ADR-002: Django backend uses Python package management
  • ADR-001: Modular architecture benefits from faster dependency management

References