uv — The Unified Python Toolchain

Parent: Python Patterns and Best Practices · Published reference · snapshot 2026-09-08 · skill lang-python/references/uv-python-toolchain.md

↓ Facts as markdown all context files

uv is an extremely fast Python package and project manager written in Rust by

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

uv — The Unified Python Toolchain

uv is an extremely fast Python package and project manager written in Rust by Astral (the Ruff team). It is a single static binary that consolidates the jobs previously spread across pip, pip-tools, virtualenv/venv, pyenv, pipx, poetry, twine, and build - typically 10-100x faster than the pip/pip-tools baseline. This reference covers the five pillars named in the brief: project/workspace management, the universal lockfile, Python-version install/pinning, the tool/pipx replacement, and the pip-compatible interface - plus the build backend, PEP 723 scripts, and configuration/caching. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#uv-the-unified-python-toolchain]
> For everyday Python idioms, async, typing, and a uv quick-start cheat sheet, > see references/python-patterns.md. For static type checkers (mypy/Pyright/ > ty/Pyrefly) see references/python-static-type-checking.md; for pytest/ > Hypothesis see references/python-testing.md. This file is the deep, > tool-specific reference for uv itself. Defer to the official docs > (https://docs.astral.sh/uv/) as the source of truth for exact flags/versions. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#uv-the-unified-python-toolchain]

Command surface at a glance

uv <command> top-level commands (uv 0.11.x): [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#command-surface-at-a-glance]
Two front-doors that confuse newcomers: the project interface (uv add, uv sync, uv run - operates on pyproject.toml + uv.lock, the recommended path) and the pip interface (uv pip ... - a drop-in low-level imperative layer with no lockfile). Don't mix them on the same environment expecting managed state; the project interface owns uv.lock, the pip interface does not. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#command-surface-at-a-glance]

Single project

uv run and uv sync auto-create the .venv, auto-install the pinned Python if missing, auto-lock, and auto-sync before running - so the venv is an implementation detail you rarely activate manually. Key files: [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#single-project]
- pyproject.toml - standard PEP 621 metadata + [tool.uv] config, [dependency-groups], [tool.uv.sources]. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#single-project]
- uv.lock - the universal lockfile (commit to git; never hand-edit). [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#single-project]
- .python-version - the pinned interpreter (written by uv python pin). [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#single-project]
- .venv/ - the project virtualenv (gitignored). [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#single-project]
Dependency groups (PEP 735, the modern replacement for [project.optional-dependencies] "extras" used as dev deps): dev is the implicit default group. Control install scope on sync/run: --group <g>, --only-group <g>, --no-dev, --no-default-groups, --all-groups. Extras (consumer-facing optional features) are separate: --extra <e>, --all-extras. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#single-project]
Dependency sources - [tool.uv.sources] redirects a dependency away from PyPI: [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#single-project]
[tool.uv.sources] is non-standard metadata that uv strips when building a distribution - it affects your dev resolution, not what downstream consumers get. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#single-project]

Workspaces (monorepo)

A workspace is multiple packages in one repo sharing one uv.lock and one .venv, each with its own pyproject.toml. Inspired by Cargo workspaces. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#workspaces-monorepo]
- Members are addressed with uv run --package <member> / uv add --package <member> <dep>. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#workspaces-monorepo]
- workspace = true sources are treated as editable - cross-package edits are live. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#workspaces-monorepo]
- Root [tool.uv.sources] apply to all members unless a member overrides them. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#workspaces-monorepo]
- Use a workspace when packages are co-released and tightly coupled; use separate projects (path/git sources) when versions must diverge or a member needs a conflicting dependency (a single shared lock forbids conflicts). [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#workspaces-monorepo]

2. The universal lockfile (`uv.lock`)

uv.lock is a universal (cross-platform) resolution: one lockfile valid for every OS, architecture, and Python version inside the project's requires-python range. A package can appear multiple times with different versions/URLs gated by environment markers (sys_platform, python_full_version, etc.); the marker chooses which entry installs on a given machine. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#2-the-universal-lockfile-uvlock]
Resolution knobs (also valid in the pip interface): [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#2-the-universal-lockfile-uvlock]
- --resolution {highest|lowest|lowest-direct} (env UV_RESOLUTION). lowest is for testing your declared lower bounds; lowest-direct lowers your direct deps but keeps transitive at highest. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#2-the-universal-lockfile-uvlock]
- --prerelease {disallow|allow|if-necessary|explicit|if-necessary-or-explicit}. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#2-the-universal-lockfile-uvlock]
- --fork-strategy {requires-python|fewest} - requires-python (default) picks the latest version compatible with each supported Python minor; fewest minimizes the number of distinct versions. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#2-the-universal-lockfile-uvlock]
- requires-python semantics: uv considers only lower bounds of dependency requires-python and ignores upper bounds (>=3.8,<4 is treated as >=3.8), because honoring upper bounds causes pathological backtracking. Your project's requires-python must be a subset of every dependency's range. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#2-the-universal-lockfile-uvlock]
Export / interop - uv.lock is uv-native; export to standard formats for other tooling: [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#2-the-universal-lockfile-uvlock]
uv reads pylock.toml (PEP 751) for install but keeps uv.lock as its native format because PEP 751 doesn't yet capture everything uv needs (e.g. full fork/marker model). Treat uv.lock as the source of truth and pylock.toml/ requirements.txt as generated artifacts. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#2-the-universal-lockfile-uvlock]
uv.lock is deterministic and committed. The cross-platform guarantee is the headline benefit over a platform-specific pip-compile requirements.txt. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#2-the-universal-lockfile-uvlock]

3. Python version install & pinning

uv downloads and manages standalone CPython/PyPy builds (python-build-standalone) - no pyenv needed, and no system Python required. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#3-python-version-install-pinning]
Selection & preference: [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#3-python-version-install-pinning]
- Request syntax: 3.12, [email protected], [email protected], >=3.11,<3.13, or a path. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#3-python-version-install-pinning]
- .python-version (project) / .python-versions pins the interpreter; requires-python in pyproject.toml bounds what is acceptable. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#3-python-version-install-pinning]
- --python-preference {only-managed|managed|system|only-system} ([tool.uv] python-preference) controls managed-vs-system priority. managed (default) prefers uv's downloads but will use a compatible system Python. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#3-python-version-install-pinning]
- --no-python-downloads (env UV_PYTHON_DOWNLOADS=never) forbids auto-download - useful in locked-down CI/containers. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#3-python-version-install-pinning]
- Automatic downloads: uvx [email protected] -c ... or uv venv will fetch a missing interpreter on demand unless downloads are disabled. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#3-python-version-install-pinning]

4. Tool / pipx replacement (`uv tool`, `uvx`)

uv runs and installs CLI tools from Python packages in isolated environments, replacing pipx. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#4-tool-pipx-replacement-uv-tool-uvx]
- uvx = uv tool run: an ephemeral environment, ideal for one-off or CI invocations; it caches the env so repeat runs are fast. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#4-tool-pipx-replacement-uv-tool-uvx]
- uv tool install is persistent: executables are symlinked (copied on Windows) into the tool bin dir. Only the package's own entry points are exposed - not its dependencies' executables. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#4-tool-pipx-replacement-uv-tool-uvx]
- If the bin dir isn't on PATH, uv warns; run uv tool update-shell. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#4-tool-pipx-replacement-uv-tool-uvx]

5. pip-compatible interface (`uv pip`)

A near-drop-in, much faster reimplementation of the pip / pip-tools workflow. Operates imperatively on an environment with no lockfile and no automatic project management - use it for legacy flows, scripts, containers, or when you explicitly want pip semantics. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#5-pip-compatible-interface-uv-pip]
Deliberate differences from pip (uv is stricter / more correct by default): [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#5-pip-compatible-interface-uv-pip]
- uv pip install does not mutate a global Python unless you pass --system or activate a venv; otherwise it targets .venv. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#5-pip-compatible-interface-uv-pip]
- uv pip compile --universal produces one marker-annotated requirements.txt valid across platforms - the pip-tools world's per-platform lock pain solved. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#5-pip-compatible-interface-uv-pip]
- uv pip sync is destructive-to-match (like pip-sync): it uninstalls anything not in the file. Use it for reproducible CI/containers. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#5-pip-compatible-interface-uv-pip]
- Resolution flags (--resolution, --prerelease, --index, --index-strategy) match the project interface. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#5-pip-compatible-interface-uv-pip]

Build backend, publishing & PEP 723 scripts

Build backend. Since mid-2025 uv init --package/--lib default to uv's own PEP 517 backend uv_build (package uv-build), zero-config for pure-Python projects; Hatchling remains a fine alternative for projects needing plugins or non-pure builds. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#build-backend-publishing-pep-723-scripts]
PEP 723 inline-script metadata - single-file scripts declare their own deps and Python, run in an isolated ephemeral env: [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#build-backend-publishing-pep-723-scripts]

Configuration & cache

Config files: [tool.uv] in pyproject.toml (project), or a standalone uv.toml (project or ~/.config/uv/uv.toml global). uv.toml wins over [tool.uv] when both exist. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#configuration-cache]
Env vars: almost every flag has one - UV_RESOLUTION, UV_PRERELEASE, UV_PYTHON, UV_PYTHON_DOWNLOADS, UV_INDEX/UV_DEFAULT_INDEX, UV_CACHE_DIR, UV_NO_CACHE, UV_PROJECT_ENVIRONMENT, UV_SYSTEM_PYTHON. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#configuration-cache]
Indexes: [[tool.uv.index]] (name + url, optional default/explicit), --index/--default-index, --index-strategy {first-index|unsafe-first-match|unsafe-best-match}. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#configuration-cache]
Cache: global content-addressed store with hardlinks into venvs (why uv is fast and disk-light). uv cache dir / uv cache clean / uv cache prune (--ci prunes safely for caching layers). --no-cache / UV_NO_CACHE for hermetic runs. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#configuration-cache]

Practical patterns

Adopt incrementally: start with uv pip install -r requirements.txt / uv venv (drop-in), then migrate to uv init + uv add + uv.lock when ready. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#practical-patterns]
Reproducible CI: uv sync --locked (or uv lock --check as a gate) so a stale lockfile fails the build instead of silently re-resolving. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#practical-patterns]
Docker: copy pyproject.toml + uv.lock first, uv sync --no-install-project --frozen for a cacheable deps layer, then copy source and uv sync --frozen. Use the ghcr.io/astral-sh/uv image or COPY --from=ghcr.io/astral-sh/uv /uv /uv. Set UV_COMPILE_BYTECODE=1, UV_LINK_MODE=copy in containers. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#practical-patterns]
GitHub Actions: astral-sh/setup-uv@v5 installs uv and caches automatically; combine with uv python install. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#practical-patterns]
Monorepo: one workspace + one uv.lock; per-service deploys via uv sync --package <svc> or uv export --package <svc>. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#practical-patterns]
Pin Python per project: uv python pin 3.12 so contributors and CI agree. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#practical-patterns]

Anti-patterns

Mixing interfaces on one env expecting managed state - uv pip install into a project .venv then uv sync will reconcile to the lock and remove your manual installs. Pick the project interface or the pip interface. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#anti-patterns]
Hand-editing uv.lock - it's generated; edit pyproject.toml and re-lock. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#anti-patterns]
Committing requirements.txt as the source of truth in a uv project - the lock is uv.lock; export requirements.txt as a derived artifact. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#anti-patterns]
Putting dev tools in [project.dependencies] - use [dependency-groups] (uv add --dev) so they don't ship to consumers. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#anti-patterns]
A workspace with conflicting dependency versions across members - a single shared lock can't satisfy a true conflict; split into separate projects with path/git sources instead. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#anti-patterns]
uv pip install without --system inside a container and then wondering why the system interpreter is empty - in containers you usually want --system or an explicitly created venv on PATH. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#anti-patterns]
Forgetting requires-python is a subset constraint - if your floor is >=3.8 but a dependency dropped 3.8, universal resolution fails; raise your floor or constrain the dep. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#anti-patterns]

Troubleshooting

"No interpreter found for Python 3.x" → uv python install 3.x, or you set --no-python-downloads/UV_PYTHON_DOWNLOADS=never in a locked env. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#troubleshooting]
Lockfile out of date in CI (uv sync --locked fails) → run uv lock locally and commit; something changed pyproject.toml without re-locking. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#troubleshooting]
"Tool executable not on PATH" after uv tool install → uv tool update-shell then restart the shell; verify with uv tool dir --bin. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#troubleshooting]
Resolution is "too constrained"/conflict → check overlapping requires-python, try --resolution lowest-direct to isolate, or uv tree --invert <pkg> to see who requires a pin. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#troubleshooting]
Editable workspace dep not picking up changes → confirm the member is in [tool.uv.workspace] members and referenced with { workspace = true } in [tool.uv.sources]; re-run uv sync. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#troubleshooting]
Private index auth → uv auth or UV_INDEX_<NAME>_USERNAME/PASSWORD; set --index-strategy if a package exists on multiple indexes. [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#troubleshooting]

References

uv official docs - https://docs.astral.sh/uv/ (projects, workspaces, resolution, tools, python-versions, pip, build-backend, export, settings) [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references]
uv resolution & universal lockfile - https://docs.astral.sh/uv/concepts/resolution/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references]
uv workspaces - https://docs.astral.sh/uv/concepts/projects/workspaces/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references]
uv tools (pipx replacement) - https://docs.astral.sh/uv/concepts/tools/ and /guides/tools/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references]
uv Python versions - https://docs.astral.sh/uv/concepts/python-versions/ and /guides/install-python/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references]
uv pip interface - https://docs.astral.sh/uv/pip/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references]
uv build backend (stable, default since 2025) - https://docs.astral.sh/uv/concepts/build-backend/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references]
PEP 751 pylock.toml - https://packaging.python.org/en/latest/specifications/pylock-toml/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references]
Real Python: Managing Python projects with uv - https://realpython.com/python-uv/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references]
pydevtools: uv complete guide / build-backend-now-stable / uv 0.8 PATH - https://pydevtools.com/handbook/explanation/uv-complete-guide/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references]
Verified locally against uv 0.11.16 (Homebrew, 2026-05) - command surface, uv init output, export formats, lock/sync flags [archived source: https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references]

Where this helps

Migrating a legacy project off pip/pip-tools/pyenv/pipx/poetry onto one fast, reproducible toolchain, especially when CI lockfile drift or slow installs are a recurring pain point. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Setting up a monorepo where multiple Python packages share dependencies and need one universal lockfile instead of per-package requirements files. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Speeding up CI/CD pipelines that need reproducible, fast dependency installs, using Docker layer caching with uv sync --frozen. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Running a one-off CLI tool without polluting a project's environment, using uvx / uv tool run as a pipx replacement. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Project ideas

Convert an existing pip/requirements.txt project to a uv-managed project incrementally: start with uv venv/uv pip install, then migrate to uv init + uv add + uv.lock. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Build a Docker image that copies pyproject.toml and uv.lock first and runs uv sync --frozen for a cacheable dependency layer, cutting rebuild time. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Set up a multi-package workspace with one shared uv.lock and per-service deploys via uv sync --package <svc>. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Wire GitHub Actions with astral-sh/setup-uv@v5 plus a uv lock --check gate so CI fails fast on a stale lockfile instead of silently re-resolving. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Common mistakes

Mixing the project interface (uv add/sync) and the pip interface (uv pip install) on the same venv and expecting both to coexist — uv sync reconciles the environment to the lock and removes manually pip-installed packages. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Hand-editing uv.lock directly instead of editing pyproject.toml and re-running uv lock. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Committing requirements.txt as the source of truth instead of uv.lock, which defeats the cross-platform lock guarantee that is uv's headline benefit. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Running uv pip install without --system inside a container and then finding the system interpreter has no packages installed. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Known issues

uv.lock's universal resolution only honors the lower bound of a dependency's requires-python and ignores upper bounds, so a project's floor must be a true subset of every dependency's supported range or resolution fails. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
[tool.uv.sources] is non-standard metadata stripped at build time — it changes what you resolve against during development but not what a downstream consumer of your published package gets. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
A workspace enforces one shared lock across all members, so packages with genuinely conflicting dependency versions can't coexist in the same workspace and must be split into separate projects. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
In locked-down CI or containers, uv's automatic managed-Python downloads must be disabled explicitly (--no-python-downloads / UV_PYTHON_DOWNLOADS=never), or a build can silently reach out to fetch an interpreter. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Where this helps

Migrating a legacy project off pip/pip-tools/pyenv/pipx/poetry onto one fast, reproducible toolchain, especially when CI lockfile drift or slow installs are a recurring pain point. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Setting up a monorepo where multiple Python packages share dependencies and need one universal lockfile instead of per-package requirements files. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Speeding up CI/CD pipelines that need reproducible, fast dependency installs, using Docker layer caching with uv sync --frozen. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Running a one-off CLI tool without polluting a project's environment, using uvx / uv tool run as a pipx replacement. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Project ideas

Convert an existing pip/requirements.txt project to a uv-managed project incrementally: start with uv venv/uv pip install, then migrate to uv init + uv add + uv.lock. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Build a Docker image that copies pyproject.toml and uv.lock first and runs uv sync --frozen for a cacheable dependency layer, cutting rebuild time. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Set up a multi-package workspace with one shared uv.lock and per-service deploys via uv sync --package <svc>. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Wire GitHub Actions with astral-sh/setup-uv@v5 plus a uv lock --check gate so CI fails fast on a stale lockfile instead of silently re-resolving. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Common mistakes

Mixing the project interface (uv add/sync) and the pip interface (uv pip install) on the same venv and expecting both to coexist — uv sync reconciles the environment to the lock and removes manually pip-installed packages. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Hand-editing uv.lock directly instead of editing pyproject.toml and re-running uv lock. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Committing requirements.txt as the source of truth instead of uv.lock, which defeats the cross-platform lock guarantee that is uv's headline benefit. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Running uv pip install without --system inside a container and then finding the system interpreter has no packages installed. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Known issues

uv.lock's universal resolution only honors the lower bound of a dependency's requires-python and ignores upper bounds, so a project's floor must be a true subset of every dependency's supported range or resolution fails. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
[tool.uv.sources] is non-standard metadata stripped at build time — it changes what you resolve against during development but not what a downstream consumer of your published package gets. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
A workspace enforces one shared lock across all members, so packages with genuinely conflicting dependency versions can't coexist in the same workspace and must be split into separate projects. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
In locked-down CI or containers, uv's automatic managed-Python downloads must be disabled explicitly (--no-python-downloads / UV_PYTHON_DOWNLOADS=never), or a build can silently reach out to fetch an interpreter. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Children

Project & workspace management (uv init/add/remove/sync/run/lock/tree, [dependency-groups] PEP 735, [tool.uv.sources], multi-package workspaces with shared uv.lock) (frontier)
Universal lockfile (uv.lock cross-platform marker resolution, --resolution highest/lowest/lowest-direct, --prerelease, --fork-strategy, --locked/--frozen/--check, requires-python subset rule) (frontier)
Lockfile export & interop (uv export to requirements.txt / pylock.toml PEP 751 / CycloneDX SBOM) (frontier)
Python version install & pinning (uv python install/pin/list/find, .python-version, python-preference managed vs system, UV_PYTHON_DOWNLOADS) (frontier)
Tool / pipx replacement (uvx / uv tool run ephemeral, uv tool install/upgrade/list/update-shell) (frontier)
pip-compatible interface (uv pip install/compile --universal/sync, uv venv, --system) (frontier)
Build backend & publishing (uv_build default since 2025, uv build, uv publish) (frontier)
PEP 723 inline-script metadata (uv run script.py, uv add --script, --with) (frontier)
Configuration & cache ([tool.uv]/uv.toml, UV_* env vars, [[tool.uv.index]], content-addressed cache) (frontier)

Frontier under this node: Build backend & publishing (uv_build default since 2025, uv build, uv publish), Configuration & cache ([tool.uv]/uv.toml, UV_* env vars, [[tool.uv.index]], content-addressed cache), Lockfile export & interop (uv export to requirements.txt / pylock.toml PEP 751 / CycloneDX SBOM), PEP 723 inline-script metadata (uv run script.py, uv add --script, --with), Project & workspace management (uv init/add/remove/sync/run/lock/tree, [dependency-groups] PEP 735, [tool.uv.sources], multi-package workspaces with shared uv.lock), Python version install & pinning (uv python install/pin/list/find, .python-version, python-preference managed vs system, UV_PYTHON_DOWNLOADS), Tool / pipx replacement (uvx / uv tool run ephemeral, uv tool install/upgrade/list/update-shell), Universal lockfile (uv.lock cross-platform marker resolution, --resolution highest/lowest/lowest-direct, --prerelease, --fork-strategy, --locked/--frozen/--check, requires-python subset rule), pip-compatible interface (uv pip install/compile --universal/sync, uv venv, --system)

← the whole tree · 3D view· how to read this page