Python uv

Overview

Expert guidance for using uv - the extremely fast Python package and project manager by Astral. Written in Rust, 10-100x faster than pip. Replaces pip, pip-tools, pipx, poetry, pyenv, and virtualenv.

Instructions

1. New Project Setup

# Create new project
uv init my-project
cd my-project

# Or initialize in current directory
uv init

Creates standard structure:

my-project/
├── .python-version
├── .gitignore
├── pyproject.toml
├── README.md
└── main.py

2. Dependency Management

# Add dependencies
uv add requests
uv add 'flask>=2.0'
uv add httpx aiofiles          # Multiple packages

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

# Add optional dependencies
uv add --optional gui pyqt6

# Remove dependencies
uv remove requests

# Sync environment with lockfile
uv sync

# Update lockfile
uv lock
uv lock --upgrade-package flask  # Upgrade specific

3. Running Code

# Run script (auto-syncs environment)
uv run main.py

# Run command in project environment
uv run pytest
uv run ruff check .

# Run with env file
uv run --env-file .env main.py

# Run with extra dependencies (not installed)
uv run --with rich main.py

Key insight: Use uv run instead of activating venv. It's faster and ensures sync.

4. Python Version Management

# Install latest Python
uv python install

# Install specific version
uv python install 3.12
uv python install 3.11 3.12    # Multiple versions

# Set as default (creates python/python3 symlinks)
uv python install --default

# List installed versions
uv python list

# Pin project to specific version
uv python pin 3.12

5. Tool Management (replaces pipx)

# Run tool without installing
uvx ruff check .
uvx black --check .

# Install tool globally
uv tool install ruff
uv tool install 'httpie>=3.0'

# Upgrade tool
uv tool upgrade ruff

# List installed tools
uv tool list

6. pip Interface (for compatibility)

# Install packages
uv pip install flask
uv pip install -r requirements.txt

# Compile requirements
uv pip compile requirements.in -o requirements.txt

# Show installed packages
uv pip list
uv pip show flask

Examples

Example: Create FastAPI Project

Input: "Create a new FastAPI project with testing"

uv init fastapi-app
cd fastapi-app
uv add fastapi uvicorn
uv add --dev pytest httpx pytest-asyncio

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

# Run development server
uv run uvicorn main:app --reload

# Run tests
uv run pytest

Example: Migrate from requirements.txt

Input: "Migrate existing project to uv"

# In project directory
uv init

# Import existing dependencies
uv add -r requirements.txt

# Remove old requirements.txt (optional)
rm requirements.txt

# Now use uv.lock for reproducibility
git add uv.lock pyproject.toml

Example: Run One-off Script

Input: "Run a script with dependencies not in project"

# Run with temporary dependencies
uv run --with pandas --with matplotlib script.py

# Or use inline metadata (PEP 723)

# /// script
# dependencies = ["pandas", "matplotlib"]
# ///

import pandas as pd
import matplotlib.pyplot as plt
# ...

uv run script.py  # Auto-installs inline deps

Example: CI/CD Setup

Input: "Setup GitHub Actions with uv"

# .github/workflows/test.yml
name: Test

on: [push, pull_request]

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

      - name: Install uv
        uses: astral-sh/setup-uv@v7

      - name: Set up Python
        run: uv python install

      - name: Install dependencies
        run: uv sync --locked --all-extras --dev

      - name: Run tests
        run: uv run pytest

      - name: Run linter
        run: uv run ruff check .

Example: Docker Production

Input: "Create Dockerfile with uv"

FROM python:3.12-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Set environment for production
ENV UV_COMPILE_BYTECODE=1
ENV UV_LINK_MODE=copy

WORKDIR /app

# Copy dependency files
COPY pyproject.toml uv.lock ./

# Install dependencies (no dev, locked versions)
RUN uv sync --locked --no-dev --no-install-project

# Copy application
COPY . .

# Install project
RUN uv sync --locked --no-dev

CMD ["uv", "run", "python", "-m", "myapp"]

Quick Reference

Task	Command
New project	uv init
Add package	uv add <pkg>
Add dev dep	uv add --dev <pkg>
Remove package	uv remove <pkg>
Sync env	uv sync
Run script	uv run <script.py>
Run command	uv run <cmd>
Install Python	uv python install 3.12
Run tool (no install)	uvx <tool>
Install tool	uv tool install <tool>

Environment Variables

Variable	Purpose
UV_COMPILE_BYTECODE=1	Compile .pyc (faster startup)
UV_NO_SYNC=1	Skip sync in uv run
UV_LINK_MODE=copy	Copy files instead of hardlink
UV_MANAGED_PYTHON=1	Only use uv-managed Python

Guidelines

Do

• Use uv run instead of activating venv
• Commit uv.lock for reproducible builds
• Use --locked in CI/CD
• Use --dev for test/lint dependencies
• Use uvx for one-off tool usage

Don't

• Activate venv manually (use uv run)
• Forget to commit uv.lock
• Mix pip and uv in same project
• Skip --locked in production

Migration Cheatsheet

Old Tool	uv Equivalent
pip install X	uv add X or uv pip install X
pip install -r requirements.txt	uv add -r requirements.txt
python script.py	uv run script.py
pipx run ruff	uvx ruff
pipx install ruff	uv tool install ruff
pyenv install 3.12	uv python install 3.12
poetry add X	uv add X
poetry install	uv sync
poetry lock	uv lock