# uv — The Unified Python Toolchain > uv is an extremely fast Python package and project manager written in Rust by Parent: [Python Patterns and Best Practices](https://llms-explorer.com/tree/python-patterns-and-best-practices/) · 22 facets · 111 facts · page: https://llms-explorer.com/tree/uv-the-unified-python-toolchain/ ## 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. — [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. — [source](https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#uv-the-unified-python-toolchain) ## Command surface at a glance - uv top-level commands (uv 0.11.x): — [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. — [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: — [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]. — [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). — [source](https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#single-project) - .python-version - the pinned interpreter (written by uv python pin). — [source](https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#single-project) - .venv/ - the project virtualenv (gitignored). — [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 , --only-group , --no-dev, --no-default-groups, --all-groups. Extras (consumer-facing optional features) are separate: --extra , --all-extras. — [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: — [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. — [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. — [source](https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#workspaces-monorepo) - Members are addressed with uv run --package / uv add --package . — [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. — [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. — [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). — [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. — [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): — [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. — [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}. — [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. — [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. — [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: — [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. — [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. — [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. — [source](https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#3-python-version-install-pinning) - Selection & preference: — [source](https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#3-python-version-install-pinning) - Request syntax: 3.12, cpython@3.12, pypy@3.10, >=3.11,<3.13, or a path. — [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. — [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. — [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. — [source](https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#3-python-version-install-pinning) - Automatic downloads: uvx python@3.12 -c ... or uv venv will fetch a missing interpreter on demand unless downloads are disabled. — [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. — [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. — [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. — [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. — [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. — [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): — [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. — [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. — [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. — [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. — [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. — [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: — [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. — [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. — [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}. — [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. — [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. — [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. — [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. — [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. — [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 or uv export --package . — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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 to see who requires a pin. — [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. — [source](https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#troubleshooting) - Private index auth → uv auth or UV_INDEX__USERNAME/PASSWORD; set --index-strategy if a package exists on multiple indexes. — [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) — [source](https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references) - uv resolution & universal lockfile - https://docs.astral.sh/uv/concepts/resolution/ — [source](https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references) - uv workspaces - https://docs.astral.sh/uv/concepts/projects/workspaces/ — [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/ — [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/ — [source](https://llms-explorer.com/sources/mdb-context-hub/uv-python-toolchain/#references) - uv pip interface - https://docs.astral.sh/uv/pip/ — [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/ — [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/ — [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/ — [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/ — [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 — [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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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 . — [source](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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 . — [source](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(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](https://llms-explorer.com/tree/uv-the-unified-python-toolchain/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Context files - [uv — The Unified Python Toolchain](https://llms-explorer.com/downloads/sources/mdb-context-hub/uv-python-toolchain.md)