Complete Guide to uv: Modern Python Package Management

uv is an extremely fast Python package and project manager, written in Rust. It provides a unified interface for managing Python dependencies, virtual environments, Python versions, and projects.

What is uv?

Core Architecture

Component	Language	Purpose	Replaces
Package Installer	Rust	Fast dependency resolution and installation	pip
Project Manager	Rust	Modern project management with lockfiles	poetry, pip-tools
Environment Manager	Rust	Virtual environment creation and management	virtualenv, venv
Python Version Manager	Rust	Install and switch Python versions	pyenv
Tool Runner	Rust	Execute CLI tools from packages	pipx
Package Publisher	Rust	Build and publish distributions	twine

Key Features

• 🚀 Unified Toolchain: Single command replacing 8+ Python tools.
• ⚡️ Performance: 10-100x faster than pip (benchmarked).
• 🗂️ Project Management: Universal lockfile support across platforms.
• 🐍 Python Management: Install and manage multiple Python versions.
• 💾 Global Cache: Disk-space efficient dependency deduplication.

---

Why Use uv?

Performance Benchmarks

Operation	pip Time	uv Time	Speed Improvement
Install requests (cold cache)	1.2s	0.08s	15x faster
Install Flask (warm cache)	0.8s	0.01s	80x faster
Resolve 50 packages	2.5s	0.03s	83x faster
Create virtual environment	0.5s	0.02s	25x faster

Workflow Comparison

Traditional Workflow (6+ tools)

# Install Python, create venv, install deps, lock, build...
pyenv install 3.11.0
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip-compile requirements.in -o requirements.txt
python -m build

Modern uv Workflow (1 tool)

# One tool for everything
uv init myproject --python 3.11.0
uv add requests flask
uv lock
uv build

---

Getting Started

Installation

Platform	Command
macOS / Linux	`curl -LsSf https://astral.sh/uv/install.sh
Windows	`powershell -c "irm https://astral.sh/uv/install.ps1
Homebrew	brew install uv

pip Command Replacements

pip Command	uv Equivalent
pip install package	uv pip install package
pip install -r reqs.txt	uv pip install -r reqs.txt
python -m venv .venv	uv venv
pip list	uv pip list
pip freeze	uv pip freeze

---

Modern Project Management

Project Initialization

Use uv init to quickly create a new Python project with a standardized structure:

# Basic usage: initialize in current directory
uv init

# Create a new project directory
uv init myproject

# Specify Python version
uv init --python 3.11

# Create an application (non-library)
uv init --app myapp

# Include a README file
uv init --readme myproject

# Create a project without virtual environment
uv init --no-venv myproject

Generated Project Structure:

myproject/
├── pyproject.toml          # Project metadata and dependencies
├── uv.lock                 # Universal lockfile (commit to Git)
├── .python-version         # Python version specification
├── README.md               # Project description (optional)
└── src/
    └── myproject/
        └── __init__.py     # Package initialization

The pyproject.toml file generated by uv init follows PEP 621 standards. For detailed explanations of each field and configuration best practices, refer to pyproject.toml Complete Guide.

Project Structure

myproject/
├── pyproject.toml          # Project metadata and dependencies
├── uv.lock                 # Universal lockfile (commit to Git)
├── .python-version          # Python version specification
├── src/                    # Source code
└── tests/                   # Test files

Dependency Management

• Add Dependency: uv add requests
• Add Dev Dependency: uv add --dev pytest
• Sync Environment: uv sync (Ensures .venv matches uv.lock)
• Run Command: uv run python main.py (Automatically handles venv)

Best Practice

Always commit uv.lock to your repository. It ensures every team member and CI environment uses the exact same dependency versions.

---

Advanced Features

Script Support

Run standalone scripts with inline dependency metadata:

# /// script
# dependencies = ["requests", "rich"]
# ///
import requests
from rich import print
print(requests.get("https://api.github.com").status_code)

Run with: uv run script.py

Tool Management

Install and run Python CLI tools globally without polluting system Python:

uv tool install ruff
uvx ruff check .  # Run without permanent installation

Python Management

uv python install 3.11 3.12  # Install specific versions
uv python list               # List available versions

---

CI/CD Integration

GitHub Actions

- uses: astral-sh/setup-uv@v3
- run: uv sync
- run: uv run pytest

Docker

FROM python:3.11-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

---

Integrating with Third-Party Package Managers

Some ecosystems (e.g., OpenMMLab) use their own package managers. uv handles the virtual environment while these tools manage their own packages.

Workflow

# 1. Create venv with uv
uv venv .venv
source .venv/bin/activate

# 2. Install the third-party package manager via uv
uv pip install openmim

# 3. Use the manager to install ecosystem packages
mim install mmdet mmdet3d mmyolo

Key Principle

uv manages the environment and pip operations; the third-party manager handles its own package versions. As long as the venv is activated before running the manager, packages install into the correct location.

Avoiding Environment Confusion

If the venv is not activated, mim install may not use the correct pip. Use one of these patterns:

# Chain activation with installation
source .venv/bin/activate && mim install mmdet

# Or invoke mim via the venv's Python directly
.venv/bin/python -m mim install mmdet

# Or use uv run
uv pip install openmim && uv run mim install mmdet

When using uv run, the environment is automatically configured correctly:

uv run mim install mmdet  # uv handles the environment automatically

---

Summary Recommendations

1. Adopt uv init: Use the project management features for new projects.
2. Use uv run: Stop manually activating virtual environments.
3. Commit uv.lock: Ensure reproducibility across all environments.
4. Use uv tool: Replace pipx for global CLI tools.