uv Advanced Usage
uv is an extremely fast Python package and project manager written in Rust. It replaces pip, pip-tools, pipx, poetry, pyenv, virtualenv, and more with a single unified tool that's 10-100x faster.
Quick Reference
| Task |
Command |
| Create project |
uv init myproject |
| Add dependency |
uv add requests |
| Add dev dependency |
uv add --dev pytest |
| Run command |
uv run python main.py |
| Lock dependencies |
uv lock |
| Sync environment |
uv sync |
| Run tool |
uvx ruff check . |
| Install Python |
uv python install 3.12 |
Core Concepts
Project Structure
myproject/
├── pyproject.toml # Project metadata and dependencies
├── uv.lock # Universal lockfile (commit this)
├── .venv/ # Virtual environment (gitignore)
└── src/
└── myproject/
pyproject.toml Essentials
[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["requests>=2.28", "rich"]
[project.optional-dependencies]
dev = ["pytest", "ruff"]
[dependency-groups]
test = ["pytest>=8.0", "pytest-cov"]
[tool.uv]
dev-dependencies = ["ruff", "mypy"]
[tool.uv.sources]
# Use git dependency during development
mylib = { git = "https://github.com/org/mylib", branch = "main" }
# Use workspace member
shared = { workspace = true }
# Use local path
utils = { path = "../utils", editable = true }
Reference Documentation
For detailed guidance on specific topics:
- Projects — Project lifecycle: init, add, run, lock, sync, build, publish
- Workspaces — Monorepo management with shared lockfiles
- Resolution — Universal resolution, constraints, overrides, conflict handling
- Docker — Container images, multi-stage builds, cache optimization
- Scripts & Tools — PEP 723 inline metadata, uvx, tool management
- Python Versions — Installing and managing Python interpreters
- Configuration — pyproject.toml, uv.toml, environment variables
- pip Interface — Drop-in pip replacement with advanced features
Common Workflows
Start a New Project
uv init myproject
cd myproject
uv add fastapi uvicorn
uv run uvicorn main:app --reload
Migrate from requirements.txt
uv init
uv add -r requirements.txt
uv lock
Create Reproducible Builds
# Lock with timestamp for reproducibility
uv lock --exclude-newer "2025-01-01"
# Export for pip compatibility
uv export --frozen > requirements.txt
Test Against Lowest Bounds
uv run --resolution lowest pytest
Key Flags
| Flag |
Purpose |
--frozen |
Use exact lockfile versions, fail if outdated |
--locked |
Use lockfile, fail if missing or outdated |
--no-dev |
Exclude development dependencies |
--all-extras |
Include all optional dependencies |
--upgrade |
Allow upgrading locked dependencies |
--resolution lowest |
Use lowest compatible versions |
--universal |
Create platform-independent resolution (pip compile) |
1---2name: uv-advanced3description: Advanced usage of uv, the extremely fast Python package and project manager from Astral. Use this skill when working with uv for project management (uv init, uv add, uv run, uv lock, uv sync), workspaces and monorepos, dependency resolution strategies (universal, platform-specific, constraints, overrides), Docker containerization, PEP 723 inline script metadata, uvx tool execution, Python version management, pip interface migration, pyproject.toml configuration, or any advanced uv workflow. Covers workspaces, resolution strategies, Docker best practices, CI/CD integration, and migration from pip/poetry/pipenv.4---5
6# uv Advanced Usage
7
8uv is an extremely fast Python package and project manager written in Rust. It replaces pip, pip-tools, pipx, poetry, pyenv, virtualenv, and more with a single unified tool that's 10-100x faster.
9
10## Quick Reference
11
12| Task | Command |
13|------|---------|
14| Create project | `uv init myproject` |
15| Add dependency | `uv add requests` |
16| Add dev dependency | `uv add --dev pytest` |
17| Run command | `uv run python main.py` |
18| Lock dependencies | `uv lock` |
19| Sync environment | `uv sync` |
20| Run tool | `uvx ruff check .` |
21| Install Python | `uv python install 3.12` |
22
23## Core Concepts
24
25### Project Structure
26
27```
28myproject/
29├── pyproject.toml # Project metadata and dependencies
30├── uv.lock # Universal lockfile (commit this)
31├── .venv/ # Virtual environment (gitignore)
32└── src/
33 └── myproject/
34```
35
36### pyproject.toml Essentials
37
38```toml
39[project]
40name = "myproject"
41version = "0.1.0"
42requires-python = ">=3.10"
43dependencies = ["requests>=2.28", "rich"]
44
45[project.optional-dependencies]
46dev = ["pytest", "ruff"]
47
48[dependency-groups]
49test = ["pytest>=8.0", "pytest-cov"]
50
51[tool.uv]
52dev-dependencies = ["ruff", "mypy"]
53
54[tool.uv.sources]
55# Use git dependency during development
56mylib = { git = "https://github.com/org/mylib", branch = "main" }
57# Use workspace member
58shared = { workspace = true }
59# Use local path
60utils = { path = "../utils", editable = true }
61```
62
63## Reference Documentation
64
65For detailed guidance on specific topics:
66
67- **[Projects](references/projects.md)** — Project lifecycle: init, add, run, lock, sync, build, publish
68- **[Workspaces](references/workspaces.md)** — Monorepo management with shared lockfiles
69- **[Resolution](references/resolution.md)** — Universal resolution, constraints, overrides, conflict handling
70- **[Docker](references/docker.md)** — Container images, multi-stage builds, cache optimization
71- **[Scripts & Tools](references/scripts-tools.md)** — PEP 723 inline metadata, uvx, tool management
72- **[Python Versions](references/python-versions.md)** — Installing and managing Python interpreters
73- **[Configuration](references/configuration.md)** — pyproject.toml, uv.toml, environment variables
74- **[pip Interface](references/pip-interface.md)** — Drop-in pip replacement with advanced features
75
76## Common Workflows
77
78### Start a New Project
79
80```bash
81uv init myproject
82cd myproject
83uv add fastapi uvicorn
84uv run uvicorn main:app --reload
85```
86
87### Migrate from requirements.txt
88
89```bash
90uv init
91uv add -r requirements.txt
92uv lock
93```
94
95### Create Reproducible Builds
96
97```bash
98# Lock with timestamp for reproducibility
99uv lock --exclude-newer "2025-01-01"
100
101# Export for pip compatibility
102uv export --frozen > requirements.txt
103```
104
105### Test Against Lowest Bounds
106
107```bash
108uv run --resolution lowest pytest
109```
110
111## Key Flags
112
113| Flag | Purpose |
114|------|---------|
115| `--frozen` | Use exact lockfile versions, fail if outdated |
116| `--locked` | Use lockfile, fail if missing or outdated |
117| `--no-dev` | Exclude development dependencies |
118| `--all-extras` | Include all optional dependencies |
119| `--upgrade` | Allow upgrading locked dependencies |
120| `--resolution lowest` | Use lowest compatible versions |
121| `--universal` | Create platform-independent resolution (pip compile) |
majiayu000