uv

Fast Python package and project manager with built-in virtual environment management.

Project Setup

uv init my-app             # App project
uv init my-lib --lib      # Library project
uv init --script script.py # Standalone script
uv python pin 3.11        # Pin Python version

Dependencies

uv add requests           # Add dependency
uv add --dev pytest       # Add dev dependency
uv add --optional ml scikit-learn  # Add optional
uv remove requests        # Remove dependency
uv tree                   # Show dependency tree
uv lock                   # Update lockfile only
uv export > requirements.txt  # Export to requirements.txt

Virtual Environment

uv sync                   # Sync dependencies
uv sync --no-dev         # Skip dev deps
uv sync --all-extras     # Include all optional
uv sync --refresh        # Recreate venv

Running Code

uv run python script.py   # Run script
uv run -m pytest         # Run module
uv run --with requests script.py  # Temp dependency
uv run --extra ml train.py  # Use optional deps
uv run --env-file .env script.py  # Load .env

Python Management

uv python list           # List versions
uv python install 3.12   # Install version
uv python pin 3.11       # Set project version
uv python upgrade --all  # Upgrade all

Tools

uvx ruff check .         # Run tool once
uv tool install ruff     # Install globally
uv tool list             # List tools
uv tool upgrade ruff     # Upgrade tool

Building & Publishing

uv build                 # Build distributions
uv publish               # Publish to PyPI

Project Versioning

uv version               # Show current version
uv version 1.2.3         # Set version
uv version --bump major  # Bump major version
uv version --bump minor  # Bump minor version
uv version --bump patch  # Bump patch version

Code Formatting

uv format                # Format Python code
uv format --check        # Check formatting without changes

Authentication

uv auth login            # Login to package index
uv auth logout           # Logout from package index
uv auth status           # Show authentication status

pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.9"
dependencies = ["requests>=2.31.0"]

[project.optional-dependencies]
ml = ["scikit-learn>=1.0.0"]

[dependency-groups]
dev = ["pytest>=7.0.0", "ruff>=0.1.0"]

Tips

• uv run handles venv automatically
• Commit uv.lock for reproducibility
• Use --with for one-off dependencies
• uvx for running tools without install
• uv sync --locked in CI
• Tools are isolated from project deps
• Fast: 10-100x faster than pip