SKILL.md
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 the
dockerskill 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](references/project-management.md)
- [Dependency management, lockfiles, and groups](references/dependency-management.md)
- [Python version management and virtual environments](references/python-environments.md)
- [Scripts, inline dependencies, and tool management](references/scripts-and-tools.md)
- [Workspace support for monorepos](references/workspaces.md)
- [FastAPI web framework patterns](references/fastapi-patterns.md)
- [Pydantic validation and data modeling](references/pydantic-validation.md)
- [Async patterns with asyncio](references/async-patterns.md)
- [Type checking with mypy and pyright](references/type-checking.md)
- [Testing with pytest](references/testing-patterns.md)
- [Logging with structlog](references/structlog-logging.md)
- [CLI applications with typer](references/cli-applications.md)
- [Docker integration and publishing](references/docker-and-publishing.md)