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
Exploreagent - Dependency audit: Use
Taskagent - Code review: Delegate to
code-revieweragent
If thedockerskill is available, delegate containerization patterns to it. If thegithub-actionsskill is available, delegate CI/CD pipeline configuration to it. If theapi-testingskill is available, delegate API testing patterns to it. If thesentry-setup-loggingskill is available, delegate error monitoring setup to it. If thepino-loggingskill is available, delegate Node.js logging patterns to it (Python equivalent covered here with structlog).
References
- Project management and pyproject.toml configuration
- Dependency management, lockfiles, and groups
- Python version management and virtual environments
- Scripts, inline dependencies, and tool management
- Workspace support for monorepos
- FastAPI web framework patterns
- Pydantic validation and data modeling
- Async patterns with asyncio
- Type checking with mypy and pyright
- Testing with pytest
- Logging with structlog
- CLI applications with typer
- Docker integration and publishing