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).
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
1---2name: python-uv3description: Modern Python development with uv, the fast Python package and project manager. Covers project management (uv init, uv add, uv sync, uv lock), virtual environments, Python version management (uv python install/pin), script runners (uv run), tool management (uvx), workspace support for monorepos, and publishing to PyPI. Includes Python patterns for FastAPI, Pydantic, async/await, type checking, pytest, structlog, and CLI tools. Use when initializing Python projects, managing dependencies with uv, configuring pyproject.toml, setting up virtual environments, running scripts, managing Python versions, building monorepos with workspaces, containerizing Python apps, or writing modern Python with type hints.4license: MIT5---6
7# Python uv
8
9## Overview
10
11uv 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.
12
13**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.
14
15**When to use:** Python project initialization, dependency management, virtual environments, Python version pinning, running scripts with inline dependencies, monorepo workspaces, tool execution, publishing packages.
16
17**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.
18
19## Quick Reference
20
21| Pattern | Command / API | Key Points |
22| -------------------- | ------------------------------------- | ---------------------------------------------- |
23| Init project | `uv init` | Creates `pyproject.toml` and `.python-version` |
24| Init library | `uv init --lib` | Creates `src/` layout with `py.typed` |
25| Init script | `uv init --script example.py` | PEP 723 inline metadata script |
26| Add dependency | `uv add requests` | Adds to `pyproject.toml`, updates lockfile |
27| Add dev dependency | `uv add --dev pytest` | Adds to `[dependency-groups]` dev group |
28| Add group dependency | `uv add --group docs mkdocs` | Custom dependency groups |
29| Add optional | `uv add --optional postgres psycopg` | Optional extras for libraries |
30| Remove dependency | `uv remove requests` | Removes from `pyproject.toml` and lockfile |
31| Lock dependencies | `uv lock` | Creates/updates `uv.lock` |
32| Upgrade in lockfile | `uv lock --upgrade-package requests` | Targeted dependency upgrade |
33| Sync environment | `uv sync` | Installs locked dependencies into `.venv` |
34| Sync for CI | `uv sync --locked` | Fails if lockfile is stale |
35| Sync frozen | `uv sync --frozen` | Skips lockfile verification |
36| Run command | `uv run python app.py` | Runs in project virtual environment |
37| Run script | `uv run script.py` | Supports PEP 723 inline dependencies |
38| Run in package | `uv run --package api pytest` | Workspace-specific execution |
39| Install Python | `uv python install 3.13` | Downloads and manages Python versions |
40| Pin Python | `uv python pin 3.12` | Writes `.python-version` file |
41| List Pythons | `uv python list` | Shows available and installed versions |
42| Run tool | `uvx ruff check .` | Ephemeral tool execution |
43| Tool with plugins | `uvx --with mkdocs-material mkdocs` | Ephemeral tool with extra packages |
44| Install tool | `uv tool install ruff` | Persistent global tool install |
45| Workspace | `[tool.uv.workspace]` | Monorepo multi-package support |
46| Build package | `uv build` | Creates sdist and wheel in `dist/` |
47| Publish | `uv publish` | Uploads to PyPI with trusted publishing |
48| Export deps | `uv export --format requirements-txt` | Generate requirements.txt from lockfile |
49
50## Common Mistakes
51
52| Mistake | Correct Pattern |
53| ------------------------------------------- | ------------------------------------------------------------------------ |
54| Using `pip install` inside uv project | `uv add` to manage via `pyproject.toml` |
55| Activating venv manually before `uv run` | `uv run` handles venv activation automatically |
56| Committing `.venv/` to version control | Add `.venv/` to `.gitignore`, commit `uv.lock` |
57| Not committing `uv.lock` | Always commit `uv.lock` for reproducible builds |
58| Using `uv sync` without `--locked` in CI | `uv sync --locked` ensures lockfile matches `pyproject.toml` |
59| Running `uv lock --upgrade` routinely | Only upgrade intentionally, use `--upgrade-package` for targeted updates |
60| Mixing `pip` and `uv` dependency management | Choose one tool for the project consistently |
61| Using `uv pip install` for project deps | Use `uv add`/`uv sync` for managed projects |
62| Forgetting `--frozen` for Docker builds | `uv sync --frozen` skips lockfile verification for faster builds |
63| Creating venv manually in uv project | `uv sync` creates and manages `.venv` automatically |
64| Using `setup.py` for new projects | Use `pyproject.toml` with a modern build backend |
65| Not using `py.typed` in libraries | `uv init --lib` includes it, required for typed packages |
66
67## Delegation
68
69- **Project scaffolding**: Use `Explore` agent
70- **Dependency audit**: Use `Task` agent
71- **Code review**: Delegate to `code-reviewer` agent
72
73> If the `docker` skill is available, delegate containerization patterns to it.
74> If the `github-actions` skill is available, delegate CI/CD pipeline configuration to it.
75> If the `api-testing` skill is available, delegate API testing patterns to it.
76> If the `sentry-setup-logging` skill is available, delegate error monitoring setup to it.
77> If the `pino-logging` skill is available, delegate Node.js logging patterns to it (Python equivalent covered here with structlog).
78
79## References
80
81- [Project management and pyproject.toml configuration](references/project-management.md)
82- [Dependency management, lockfiles, and groups](references/dependency-management.md)
83- [Python version management and virtual environments](references/python-environments.md)
84- [Scripts, inline dependencies, and tool management](references/scripts-and-tools.md)
85- [Workspace support for monorepos](references/workspaces.md)
86- [FastAPI web framework patterns](references/fastapi-patterns.md)
87- [Pydantic validation and data modeling](references/pydantic-validation.md)
88- [Async patterns with asyncio](references/async-patterns.md)
89- [Type checking with mypy and pyright](references/type-checking.md)
90- [Testing with pytest](references/testing-patterns.md)
91- [Logging with structlog](references/structlog-logging.md)
92- [CLI applications with typer](references/cli-applications.md)
93- [Docker integration and publishing](references/docker-and-publishing.md)
oakoss