If you've ever stared at a terminal watching pip install crawl through dozens of packages, you know the frustration. The standard Python setup ritual — install pyenv, create a virtualenv, activate it, pin your Python version, wait several minutes for pip to resolve dependencies — is slow and error-prone.
uv changes the equation. Built in Rust by Astral (the team behind the popular Ruff linter), it's a Python package manager that's 10–100x faster than pip. When you combine it with Claude Code, environment setup and dependency management practically take care of themselves. I switched three active Python projects to uv over a weekend and haven't looked back.
What Is uv, and Why Does It Matter Now?
uv is a fast, all-in-one Python project management tool. Where you once needed pyenv + virtualenv + pip (three separate tools with three separate mental models), uv handles all of it in a single binary:
- Drop-in pip replacement: swap
pip installforuv pip installand you're done — no learning curve - Built-in virtual environment management: no more juggling virtualenv or conda separately
- Python version management:
uv python install 3.12installs the interpreter itself, no pyenv required - Modern
pyproject.tomlsupport: works natively with the current Python packaging standards (PEP 517/518/660) - Lockfile support:
uv.lockgives you fully reproducible environments, unlike requirements.txt
A concrete speed comparison: installing numpy with pip on a cold cache typically takes 20–30 seconds. With uv, the same install completes in 2–3 seconds. For a project with 30+ dependencies, that gap compounds significantly. For CI pipelines that run dozens of times per day, the time savings are substantial.
By 2026, uv adoption has spread rapidly across open-source projects and professional development teams. Anthropic's own Python SDK documentation recommends uv for setting up development environments, which tells you something about where the ecosystem is heading.
Why Claude Code + uv Is a Natural Fit
When building Python projects with Claude Code, the typical friction points are dependency decisions: which packages do I actually need, which versions are compatible with each other, and how should I separate dev and production dependencies?
With uv + Claude Code, Claude watches what you're building and proposes — or directly adds — the right packages as it understands your intent. This is qualitatively different from using pip manually, where you have to figure out the dependency graph yourself before Claude can help.
Give Claude Code a prompt like this:
Build a user authentication API using FastAPI + SQLAlchemy + Alembic.
Use uv for environment management and keep dev and production dependencies separate.
Claude Code executes the full setup without asking for clarification:
# Initialize project (virtual environment created automatically in .venv/)
uv init myapi
cd myapi
# Production dependencies
uv add fastapi uvicorn sqlalchemy alembic python-jose passlib
# Development-only dependencies (won't be included in production builds)
uv add --dev pytest httpx ruff mypyThe pyproject.toml is updated automatically, and the packages install in seconds. Compared to manually managing requirements.txt and a separate dev-requirements.txt, this workflow is noticeably cleaner.
Step-by-Step: Setting Up a Project From Scratch
Step 1: Install uv
Installing uv takes under a minute:
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Verify installation
uv --version
# uv 0.5.xIf you see uv: command not found after installing, you likely need to update your PATH. Claude Code can fix this for you — just tell it the error message and it will provide the exact shell configuration command for your environment.
Step 2: Let Claude Code Scaffold the Project
In your Claude Code session:
Create a Python 3.12 project using uv.
Base it on a FastAPI server that includes:
- A health check endpoint
- Environment variable loading with python-dotenv
- Structured logging configuration
Set up the complete project skeleton.
Claude Code generates a project like this:
myapi/
├── pyproject.toml # Dependencies + project metadata
├── .python-version # "3.12" — read automatically by uv
├── uv.lock # Exact dependency versions (commit this)
├── .venv/ # Virtual environment (auto-created by uv init)
├── src/
│ └── myapi/
│ ├── __init__.py
│ ├── main.py
│ └── config.py
└── tests/
└── test_main.py
The pyproject.toml Claude Code generates:
[project]
name = "myapi"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
"fastapi>=0.115",
"uvicorn[standard]>=0.32",
"python-dotenv>=1.0",
]
[project.optional-dependencies]
dev = [
"pytest>=8.0",
"httpx>=0.27",
"ruff>=0.8",
]
[tool.ruff.lint]
select = ["E", "F", "I"]Notice the uv.lock file. Unlike requirements.txt, the lockfile pins every package at the transitive level, so any developer (or CI runner) who runs uv sync will get an identical environment. This eliminates the "works on my machine" class of bugs.
Step 3: Add Dependencies Mid-Development
When you need a new library while building:
I want to add async PostgreSQL support with SQLAlchemy.
Add the packages with uv and write the database connection config.
Claude Code runs:
uv add sqlalchemy[asyncio] asyncpg alembicThe pyproject.toml and uv.lock both update automatically. Claude Code will sometimes add dependencies proactively too — if you ask for database-querying code and it detects the driver isn't listed, it adds the package before writing the implementation.
Common Issues and How Claude Code Resolves Them
Issue 1: PATH not updated after installation
If uv isn't found after installing, the binary is installed but your shell doesn't know where to look. Tell Claude Code: "uv shows command not found after installation." It will identify your shell (bash, zsh, fish, etc.) and provide the exact lines to add to your shell config, plus remind you to either restart your terminal or source the config file.
Issue 2: Migrating an existing requirements.txt project
Prompt Claude Code:
I have an existing Python project with requirements.txt and dev-requirements.txt.
Migrate it to uv with a proper pyproject.toml, keeping dev and production deps separate.
Claude Code reads your existing requirements files, infers the dependency grouping, and generates a pyproject.toml. If there are version conflicts during the migration, it proposes resolutions rather than leaving you to debug pip's error messages manually.
Issue 3: uv in CI/CD pipelines
For GitHub Actions:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up uv
uses: astral-sh/setup-uv@v4
with:
version: "0.5.x"
- name: Install dependencies
run: uv sync --frozen # Uses uv.lock for reproducibility
- name: Run tests
run: uv run pytest tests/ -v
- name: Check formatting and types
run: |
uv run ruff check .
uv run mypy src/The --frozen flag tells uv to use the lockfile exactly as-is rather than resolving dependencies fresh. This is what you want in CI: fully reproducible builds, with no risk of a new transitive dependency version breaking your tests.
Understanding the uv Lockfile
One detail worth understanding before you dive in: the uv.lock file is different from what pip freeze > requirements.txt produces. Here's why that matters:
requirements.txtfrom pip freeze: lists the exact packages installed in your current environment, but doesn't record why each package is there. Adding a new dependency can silently upgrade or downgrade existing ones.uv.lock: records the complete dependency graph, including every transitive dependency and its exact version, along with hash verification for security. Runninguv sync --frozenanywhere produces byte-for-byte identical installed packages.
The practical implication: you should commit uv.lock to version control. When a teammate clones your repo, they run uv sync and immediately have the exact same environment you do — including the same transitive dependency versions.
Migrating from pip Incrementally
uv is designed as a backward-compatible superset of pip. You don't need to migrate everything at once:
# Start using uv immediately with your existing workflow
uv pip install -r requirements.txt # Same behavior as pip, just faster
# When you're ready, start a new project the uv-native way
uv init next-projectClaude Code can analyze your existing project and propose a migration plan that fits your timeline — whether you want to go all-in immediately or gradually move toward the uv-native workflow while keeping your production setup stable.
For building a production-grade API on this foundation, see the Claude Code × FastAPI Production API Guide. If you want the complete picture from environment setup through testing and deployment, the Claude Code Python Development Complete Guide covers the full lifecycle.
Your First Move
Run uv pip install -r requirements.txt on an existing project right now. The speed difference is immediately obvious, and it's the lowest-friction way to experience what uv offers. Once that clicks, start your next project with uv init and hand dependency management to Claude Code. The time you save on environment setup goes directly into writing code that actually matters.