tangledgroup uv 0.11.21
uv is an extremely fast Python package manager and resolver, written in Rust. It replaces pip, pip-tools, virtualenv, pipx, and more with a single unified tool. Version 0.11.21 (released 2026-06-11) adds packaged apps as the default for uv init, extends uv upgrade with per-constraint updates, introduces environment.root in workspace metadata, and adds CPython 3.13.14 and 3.14.6.
Overview
uv provides five independent interfaces that can be used together or separately:
- Projects — Full project management with
pyproject.toml, lockfiles, and automatic environments - Scripts — Standalone Python scripts with inline dependency metadata (PEP 723)
- Tools — One-off or installed CLI tools via
uvx/uv tool - Python versions — Install, discover, and manage Python interpreters
- pip interface — Drop-in replacement for
pip,pip-tools, andvirtualenv
Core workflow (projects)
uv init my-project # Create a new project
cd my-project
uv add requests # Add dependency (auto-locks + syncs)
uv run python main.py # Run in project environment
uv lock # Explicitly update lockfile
uv sync # Explicitly sync environment
uv build # Build sdist + wheel
uv publish # Publish to PyPI
Quick reference by task
| Task | Command |
|---|---|
| Create project | uv init <name> (packaged/src layout by default) / uv init --no-package / uv init --lib |
| Add dependency | uv add <package> / uv add --dev pytest / uv add --optional extra pkg |
| Remove dependency | uv remove <package> |
| Run command | uv run <command> / uv run --with httpx script.py |
| Lock dependencies | uv lock / uv lock --upgrade / uv lock --upgrade-package pkg |
| Sync environment | uv sync / uv sync --extra foo / uv sync --no-dev |
| Upgrade dependency | uv upgrade <package> (preview) |
| Run tool (ephemeral) | uvx ruff / uvx ruff@0.6.0 check |
| Install tool (persistent) | uv tool install ruff |
| Create venv | uv venv / uv venv --python 3.12 |
| pip install | uv pip install flask (requires active venv) |
| pip compile | uv pip compile requirements.in -o requirements.txt |
| Install Python | uv python install 3.12 |
| List Python versions | uv python list |
| Pin Python version | uv python pin 3.12 |
| Build package | uv build / uv build --wheel / uv build --sdist |
| Publish package | uv publish |
| View dependency tree | uv tree |
| Export lockfile | uv export --format requirements.txt / uv export --format pylock.toml |
| Cache management | uv cache clean / uv cache prune --ci |
| Run ty (type check) | uv check (preview) |
Gotchas
uv initdefaults to packaged apps — since 0.11.21,uv initcreates asrc/layout with[build-system]by default. Useuv init --no-packagefor flat layout without a build system, oruv init --barefor minimal.uv runauto-locks and syncs — by default,uv runensures the lockfile and environment are up-to-date before running. Use--lockedto error if outdated,--frozento skip checking, or--no-syncto skip syncing.- Scripts with inline metadata are isolated from projects — even inside a project directory, a script with
# /// scriptmetadata runs in its own environment, ignoring the project's dependencies. This is intentional and cannot be disabled per-script. uvxvsuv run --with—uvx toolruns isolated from any project. If the tool needs your project installed (e.g.,pytest,mypy), useuv run pytestinstead ofuvx pytest.uv syncremoves extraneous packages by default — unlikeuv run,uv syncperforms "exact" syncing. Use--inexactto retain extra packages. Conversely,uv runuses inexact syncing by default; use--exactfor exact syncing.tool.uv.sourcesis uv-only — sources defined in[tool.uv.sources]are ignored by other tools (pip, build, etc.). Useuv lock --no-sourcesoruv build --no-sourcesto test compatibility.- Build system determines install behavior — without a
[build-system]table, uv won't build/install the project itself (only its dependencies). Add a build system or settool.uv.package = trueto force installation. - Workspaces share one lockfile — all workspace members must be compatible. Use
conflictsdeclarations for incompatible extras/groups across members. --systemflag required for non-virtualenv targets — uv refuses to modify system Python by default. Use--systemexplicitly (appropriate in CI/containers).- Cache directory matters for performance — keep the cache on the same filesystem as the target environment to enable hard-linking instead of slow copies.
- Free-threaded Python requires explicit request — use
3.13tor3.13+freethreadedto select free-threaded CPython 3.13+. For 3.14+, it's available but GIL-enabled is still preferred by default. uv upgradeis preview —uv upgrade <package>(from 0.11.20) updates dependency constraints. Git revisions are rejected inuv upgrade. Use--upgrade-packagewithuv lockfor the stable equivalent.
References
- 01-projects.md — Project creation (packaged default), structure, dependencies, lockfiles, syncing, running commands
- 02-scripts.md — Standalone scripts with inline metadata (PEP 723), shebangs, locking scripts
- 03-tools.md — Running and installing tools with
uvx/uv tool, version pinning, extras, plugins - 04-python-versions.md — Installing, discovering, and managing Python interpreters
- 05-pip-interface.md — pip-compatible commands: venv, install, compile, sync, constraints, overrides
- 06-dependencies.md — Dependency sources (Git, URL, path, workspace), workspaces, build isolation, editable installs
- 07-resolution.md — Resolution strategies, package indexes, authentication, constraints, overrides, reproducibility
- 08-advanced.md — Caching, configuration files, building/publishing, export formats, workspace conflicts