The Complete uv Guide 2026: The Lightning-Fast Python Package Manager by Astral

Python developers finally don't have to agonize over choosing between pip, poetry, and pipenv anymore. uv, built by the team behind Ruff, is reshaping the Python package management landscape at a remarkable pace.

What is uv?

uv is a Python package and project manager written in Rust, built with a single design goal: blazing speed.

The Astral team — the same folks who built Ruff — poured all their experience from high-performance Rust tooling into uv. The result? 10-100x faster than pip.

📦 GitHub: https://github.com/astral-sh/uv ⭐ Stars: 50k+ (mid-2026) 📄 License: MIT

Installing uv

Installing uv is dead simple — just one command:

# Officially recommended — install script
curl -LsSf https://astral.sh/uv/install.sh | sh

After installation, verify it's working:

uv --version
# uv 0.7.x

If you're on Homebrew (macOS/Linux):

brew install uv

Or install it with pipx:

pipx install uv

Quick Start: Your First Project

Initialize a Project

# Create a new project (automatically generates pyproject.toml + virtual environment)
uv init my-app
cd my-app

Here's what the file structure looks like:

my-app/
├── .python-version    # Pins the Python version
├── pyproject.toml     # Project configuration
├── README.md
├── main.py
└── uv.lock            # Dependency lock file

The pyproject.toml is beautifully clean:

[project]
name = "my-app"
version = "0.1.0"
description = "Add your description here"
requires-python = ">=3.12"
dependencies = []

Adding Dependencies

# Add production dependencies (automatic resolution + installation + locking)
uv add requests
uv add fastapi
uv add "pydantic>=2.0"

# Add dev dependencies
uv add --dev pytest ruff mypy

One command handles it all: dependency resolution → download → install → update uv.lock. The whole process typically takes just a few seconds.

Running Your Code

# Run a script in the virtual environment
uv run python main.py

# Run installed tools
uv run pytest
uv run ruff check .

uv run automatically activates the project's virtual environment. No more manual source .venv/bin/activate.

Advanced Features

Managing Multiple Python Versions

uv comes with a built-in Python version manager. You can download and manage multiple Python versions effortlessly:

# List installed Python versions
uv python list

# Install a specific Python version
uv python install 3.13
uv python install 3.11

# Pin a Python version for your project
uv python pin 3.13

# Run with a specific version
uv run --python 3.11 python main.py

This solves a long-standing pain point for Python developers — pyenv is no longer needed.

Workspaces

If your project has multiple packages, uv's workspace feature is a great fit:

# Initialize a workspace
uv init --package packages/core
uv init --package packages/cli

In pyproject.toml:

[tool.uv.workspace]
members = ["packages/*"]

Script Aliases

uv lets you define script aliases right in pyproject.toml:

[tool.uv.scripts]
dev = "uvicorn main:app --reload"
test = "pytest tests/"
lint = "ruff check . && mypy src/"

Then run them directly:

uv run dev
uv run test

CI/CD Integration

Using uv in GitHub Actions:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true

      - name: Set up Python
        run: uv python install

      - name: Install dependencies
        run: uv sync --frozen

      - name: Run tests
        run: uv run pytest

The enable-cache: true setting caches uv's package downloads. The CI speedup is dramatic.

Speed Comparison: uv vs pip/poetry

Here are the official Astral benchmark numbers (installing Django and all its dependencies):

So why is uv so fast?

1. Rust implementation — The dependency resolution engine is written in Rust, orders of magnitude faster than Python
2. Global cache — Once a package is downloaded, it's cached globally and shared across projects via hard links
3. Parallel downloads — Multiple packages download simultaneously, fully utilizing your network bandwidth
4. Smart caching — Resolution results are also cached, eliminating redundant computation

Migrating from pip/poetry

Migrating from pip

# Create a project from an existing requirements.txt
uv pip install -r requirements.txt

# Or create a new project and import
uv init
uv add -r requirements.txt

Migrating from poetry

# Sync dependencies directly from pyproject.toml
uv sync

# Re-lock if needed
uv lock

uv is fully compatible with the pyproject.toml format. Most poetry projects can switch over without any hassle.

Quick Command Reference

# Project management
uv init <name>           # Create a new project
uv add <package>         # Add a dependency
uv remove <package>      # Remove a dependency
uv sync                  # Sync dependencies (like pip install -e .)
uv lock                  # Re-lock dependencies

# Running things
uv run <command>         # Run a command in the virtual environment
uv tool run <tool>       # Run a temporary tool (like pipx run)
uv tool install <tool>   # Install a global tool

# Python management
uv python install <ver>  # Install a Python version
uv python list           # List installed versions
uv python pin <ver>      # Pin the project's Python version

# Cache
uv cache dir             # Show the cache directory
uv cache clean           # Clean the cache

Summary

uv is quickly becoming the new standard tool for Python developers. Built by the Ruff team, it's incredibly fast, has a clean API design, and is fully open-source.

Recommended use cases:

• ✅ New projects — just uv init and go
• ✅ CI/CD — cache-friendly, build speeds improve significantly
• ✅ Multi-Python-version projects — built-in version management
• ✅ Migrating from poetry/pipenv — full pyproject.toml compatibility

If you're still using pip + venv or poetry, give uv a serious try. Once you've experienced near-instant package installation, there's no going back.

🔗 Official docs: https://docs.astral.sh/uv/ 🔗 GitHub: https://github.com/astral-sh/uv