Python uv

Overview

uv is an extremely fast Python package and project manager written in Rust, designed to replace pip, pip-tools, pipx, poetry, pyenv, and virtualenv. It provides unified project management, dependency resolution, Python version management, and tool execution with 10-100x speed improvements over traditional tools.

Key capabilities: Project initialization, dependency locking and syncing, Python version management, PEP 723 inline script dependencies, ephemeral tool execution via uvx, monorepo workspaces with shared lockfiles, and package building/publishing.

When to use: Python project initialization, dependency management, virtual environments, Python version pinning, running scripts with inline dependencies, monorepo workspaces, tool execution, publishing packages.

When NOT to use: Non-Python projects, conda-managed scientific computing environments with system-level binary dependencies, projects locked to legacy setup.py-only workflows.

Quick Reference

Pattern	Command / API	Key Points
Init project	`uv init`	Creates `pyproject.toml` and `.python-version`
Init library	`uv init --lib`	Creates `src/` layout with `py.typed`
Init script	`uv init --script example.py`	PEP 723 inline metadata script
Add dependency	`uv add requests`	Adds to `pyproject.toml`, updates lockfile
Add dev dependency	`uv add --dev pytest`	Adds to `[dependency-groups]` dev group
Add group dependency	`uv add --group docs mkdocs`	Custom dependency groups
Add optional	`uv add --optional postgres psycopg`	Optional extras for libraries
Remove dependency	`uv remove requests`	Removes from `pyproject.toml` and lockfile
Lock dependencies	`uv lock`	Creates/updates `uv.lock`
Upgrade in lockfile	`uv lock --upgrade-package requests`	Targeted dependency upgrade
Sync environment	`uv sync`	Installs locked dependencies into `.venv`
Sync for CI	`uv sync --locked`	Fails if lockfile is stale
Sync frozen	`uv sync --frozen`	Skips lockfile verification
Run command	`uv run python app.py`	Runs in project virtual environment
Run script	`uv run script.py`	Supports PEP 723 inline dependencies
Run in package	`uv run --package api pytest`	Workspace-specific execution
Install Python	`uv python install 3.13`	Downloads and manages Python versions
Pin Python	`uv python pin 3.12`	Writes `.python-version` file
List Pythons	`uv python list`	Shows available and installed versions
Run tool	`uvx ruff check .`	Ephemeral tool execution
Tool with plugins	`uvx --with mkdocs-material mkdocs`	Ephemeral tool with extra packages
Install tool	`uv tool install ruff`	Persistent global tool install
Workspace	`[tool.uv.workspace]`	Monorepo multi-package support
Build package	`uv build`	Creates sdist and wheel in `dist/`
Publish	`uv publish`	Uploads to PyPI with trusted publishing
Export deps	`uv export --format requirements-txt`	Generate requirements.txt from lockfile

Common Mistakes

Mistake	Correct Pattern
Using `pip install` inside uv project	`uv add` to manage via `pyproject.toml`
Activating venv manually before `uv run`	`uv run` handles venv activation automatically
Committing `.venv/` to version control	Add `.venv/` to `.gitignore`, commit `uv.lock`
Not committing `uv.lock`	Always commit `uv.lock` for reproducible builds
Using `uv sync` without `--locked` in CI	`uv sync --locked` ensures lockfile matches `pyproject.toml`
Running `uv lock --upgrade` routinely	Only upgrade intentionally, use `--upgrade-package` for targeted updates
Mixing `pip` and `uv` dependency management	Choose one tool for the project consistently
Using `uv pip install` for project deps	Use `uv add`/`uv sync` for managed projects
Forgetting `--frozen` for Docker builds	`uv sync --frozen` skips lockfile verification for faster builds
Creating venv manually in uv project	`uv sync` creates and manages `.venv` automatically
Using `setup.py` for new projects	Use `pyproject.toml` with a modern build backend
Not using `py.typed` in libraries	`uv init --lib` includes it, required for typed packages

Delegation

Project scaffolding: Use Explore agent
Dependency audit: Use Task agent
Code review: Delegate to code-reviewer agent

If the docker skill is available, delegate containerization patterns to it. If the github-actions skill is available, delegate CI/CD pipeline configuration to it. If the api-testing skill is available, delegate API testing patterns to it. If the sentry-setup-logging skill is available, delegate error monitoring setup to it. If the pino-logging skill is available, delegate Node.js logging patterns to it (Python equivalent covered here with structlog).

python-uv

Python uv

Overview

Quick Reference

Common Mistakes

Delegation

References