June 28, 2025

uv: The Lightning-Fast Python Package Manager

Python package management just got a massive upgrade. uv delivers 10-100x faster performance than pip while replacing your entire Python toolchain. Built in Rust by Astral (creators of Ruff), it’s rapidly becoming the new standard for Python development.

Why switch from pip to uv?

Speed that transforms your workflow:

Package installation: 10-100x faster than pip
Virtual environment creation: 80x faster than python -m venv
Streamlit Cloud reduced deployment times by 55% after switching

One tool to rule them all:

Replace pip, pip-tools, pipx, poetry, pyenv, and virtualenv
Single binary with zero Python dependencies
Consistent interface across all operations

Installation

# Linux/macOS (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Using Homebrew
brew install uv

# Verify installation
uv --version

Core commands you’ll use daily

Python version management

uv manages Python installations directly - no more pyenv or manual downloads:

# Install Python versions
uv python install 3.12
uv python install 3.11.9
uv python install 3.10

# List available versions
uv python list --all-versions

# List installed versions
uv python list

# Pin project to specific version
uv python pin 3.12  # Creates .python-version

# Use specific Python version
uv venv --python 3.11
uv run --python 3.12 python script.py

Starting a new project

# Create project with specific Python
uv init my-project --python 3.12
cd my-project

# uv automatically creates:
# - pyproject.toml (modern Python standard)
# - .python-version (pins Python version)
# - .gitignore
# - README.md
# - main.py

Managing dependencies

# Add packages (auto-creates venv if needed)
uv add requests fastapi

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

# Update packages
uv sync --upgrade

# Remove packages
uv remove unused-package

Running your code

No more manual virtual environment activation! uv handles everything:

# Run scripts
uv run python main.py

# Run tools
uv run pytest
uv run black .

# Run without installing globally
uvx ruff check .  # Like npx for Python!

Quick migration guide: pip → uv

What you want	Old way (pip)	New way (uv)
Install Python	`pyenv install 3.12`	`uv python install 3.12`
Create venv	`python -m venv .venv`	`uv venv` (or auto-created)
Create venv with specific Python	`python3.11 -m venv .venv`	`uv venv --python 3.11`
Install package	`pip install requests`	`uv add requests`
Install from requirements	`pip install -r requirements.txt`	`uv pip install -r requirements.txt`
Run script	`source .venv/bin/activate && python main.py`	`uv run python main.py`
Run with specific Python	`python3.11 script.py`	`uv run --python 3.11 python script.py`
Install global tool	`pipx install black`	`uv tool install black`

Practical example: FastAPI project

Let’s build a simple API to see uv in action:

# 1. Create project with Python 3.12
uv init weather-api --python 3.12
cd weather-api

# 2. Add dependencies
uv add fastapi uvicorn httpx

# 3. Create main.py
cat > main.py << 'EOF'
from fastapi import FastAPI
import httpx
import sys

app = FastAPI()

@app.get("/")
async def root():
    return {
        "message": "Weather API with uv!",
        "python_version": sys.version
    }

@app.get("/weather/{city}")
async def get_weather(city: str):
    # Simulated weather data
    return {
        "city": city,
        "temperature": 22,
        "condition": "sunny",
        "powered_by": "uv"
    }

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
EOF

# 4. Run the API (uses Python 3.12 automatically)
uv run python main.py

# 5. Test with different Python version
uv run --python 3.11 python main.py

That’s it! No virtual environment activation, no pip freeze, just fast and simple.

Best practices

Project structure

my-project/
├── pyproject.toml      # Single source of truth
├── .python-version     # Python version for project
├── uv.lock            # Commit this for reproducibility
├── src/
│   └── my_project/
└── tests/

Python version strategies

# For libraries - support multiple versions
uv init my-lib --python ">=3.9"

# For applications - pin specific version
uv init my-app --python 3.12
uv python pin 3.12

# Test against multiple Python versions
uv run --python 3.10 pytest
uv run --python 3.11 pytest
uv run --python 3.12 pytest

Dependency management

# Use constraints wisely
uv add 'django>=4.0,<5.0'  # For compatibility
uv add 'numpy==1.24.3'     # Pin critical deps

# Organize by purpose
uv add --dev pytest mypy   # Dev tools
uv add --group docs sphinx # Optional groups

CI/CD with GitHub Actions

name: Test
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv python install ${{ matrix.python-version }}
      - run: uv sync --locked
      - run: uv run pytest

Common gotchas and solutions

Don’t activate virtual environments manually:

# ❌ Old habit
source .venv/bin/activate
python main.py

# ✅ Let uv handle it
uv run python main.py

Run from project root:

# ❌ Can cause import issues
cd src && python ../scripts/test.py

# ✅ Always from root
uv run python scripts/test.py

Cache management:

# Check cache size
uv cache info

# Clean periodically
uv cache clean

What’s new in 2024-2025

Universal lockfiles for cross-platform reproducibility
Python version management built-in (uv python install)
10-100x performance maintained across all operations
55,000+ GitHub stars and rapid adoption
Official PyCharm support and growing ecosystem

Should you switch?

Yes, if you want:

Dramatically faster dependency installation
Simpler project management
One tool instead of five
Modern Python development experience

Start with:

New projects (zero migration needed)
CI/CD pipelines (massive time savings)
Development environments (immediate productivity boost)

The Python ecosystem is rapidly adopting uv as the next-generation standard. Starting today means joining a growing community that’s already experiencing the future of Python package management.

Ready to go 10x faster? → curl -LsSf https://astral.sh/uv/install.sh | sh