uv: Fast Python Package and Project Manager in Rust
What uv is
uv is a Python package and project manager written in Rust by Astral, the company behind the Ruff linter and the ty type checker. The README describes it as "an extremely fast Python package and project manager, written in Rust" and sets out a broad goal: "a single tool to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more."
It targets two audiences at once. Teams starting fresh can use the project interface (uv init, uv add, uv run, uv lock, uv sync), which manages the virtual environment for them. Teams with an existing requirements.txt workflow can keep it and swap in the uv pip interface, which the docs call "a drop-in replacement for common pip, pip-tools, and virtualenv commands". uv "does not rely on or invoke pip".
The repository is astral-sh/uv, created on 2 October 2023, written in Rust and developed on the main branch. The README states that uv is licensed under "either of" the Apache License 2.0 or the MIT licence "at your option", and the repository carries both LICENSE-APACHE and LICENSE-MIT (the MIT file reads "Copyright (c) 2025 Astral Software Inc."). PyPI lists the licence expression as MIT OR Apache-2.0. GitHub's API reports only Apache-2.0 because it picks up a single licence file; the dual licence is what the project itself declares.
How it works
Resolver, cache and linking
The README credits the PubGrub algorithm for the dependency resolver and Cargo for the Git implementation, and names pnpm, Orogene and Bun as inspiration for its optimisations. The cache is central to the design. The caching docs describe it as "aggressive": registry downloads respect HTTP caching headers, Git dependencies are cached by fully resolved commit hash, and local directories are keyed on the modification time of pyproject.toml, setup.py or setup.cfg. Installed files are linked from the cache into each environment rather than copied; BENCHMARKS.md notes that uv uses reflinking on macOS and hardlinking on Linux. The cache docs therefore advise keeping the cache "on the same file system as the Python environment", because otherwise uv "must fall back to slower copy operations". The cache supports concurrent readers and writers.
Universal lockfile
Projects get a uv.lock file next to pyproject.toml. The project-layout docs call it a "universal or cross-platform lockfile that captures the packages that would be installed across all possible Python markers such as operating system, architecture, and Python version". It is TOML, meant to be committed, and "specific to uv and not usable by other tools". uv also reads and writes the standardised PEP 751 pylock.toml format as an export target and in uv pip, but keeps uv.lock for projects because some features cannot be expressed in the standard format. The resolution docs add that upper bounds on requires-python in dependencies are ignored.
Managed Python
uv distinguishes "managed" interpreters it downloads itself from "system" interpreters it finds on PATH (anything installed by pyenv counts as system). By default the python-preference setting is managed, which prefers managed installs over system ones, but still prefers a suitable system interpreter over a new download. If nothing matches, uv downloads one automatically, and the docs note that "the available Python versions are frozen for each uv release", so a new CPython patch release may require a newer uv.
Key features
- Project management.
uv init,uv add,uv remove,uv lock,uv sync,uv runanduv tree, with automatic locking and syncing whenever a command touches the project environment. - Cargo-style workspaces. Several packages in one repository share a single lockfile; members reference each other with
{ workspace = true }sources and are installed as editable. - Inline script metadata. PEP 723
/// scriptblocks declare dependencies and a Python requirement inside a single.pyfile;uv runbuilds a cached environment for it, anduv lock --scriptwrites an adjacent lockfile. - Tools.
uvx(an alias foruv tool run) runs a CLI from a package in a disposable cached environment;uv tool installkeeps it and links its executables ontoPATH, much like pipx. - Python version management.
uv python install,list,pinandupgrade, covering CPython (including free-threaded and debug variants), PyPy, GraalPy and Pyodide distributions. - pip-compatible interface.
uv venv,uv pip install,uv pip compileanduv pip sync, with extras such as--universalresolution, overrides, alternative resolution strategies andpylock.tomloutput. - Reproducibility controls.
--exclude-newerlimits resolution to files uploaded before a timestamp; the same option accepts durations like1 weekas a "dependency cooldown" to delay brand-new releases. - Safer index handling. With several indexes, uv by default stops at the first index that has a package, which the compatibility guide explains is meant to block dependency-confusion attacks; pip-style merging is opt-in via
--index-strategy. - Build and publish.
uv build,uv publishand the defaultuv_buildbackend.
Getting started
The README offers standalone installers that need neither Rust nor Python. On macOS and Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
On Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv is also on PyPI. The installation guide recommends an isolated environment such as pipx, but plain pip works:
pipx install uv
pip install uv
Homebrew, WinGet, Scoop, Docker and Cargo are also listed. Only the standalone installer supports self-updating:
uv self update
A first project, following the README:
uv init example
uv add ruff
uv run ruff check
uv lock
uv sync
Single-file scripts get their dependencies written into the file itself and run in an isolated environment:
uv add --script example.py 'requests<3' 'rich'
uv run example.py
Tools and interpreters:
uv tool install ruff
uvx ruff@latest --version
uv python install 3.12 3.13 3.14
uv python pin 3.11
Existing pip-tools users can stay with requirements files:
uv pip compile requirements.in -o requirements.txt
uv venv
uv pip sync requirements.txt
Hands-on: uv 0.13.9 on a Linux VM
Everything in this section was run on 18 November 2026 in a Linux cloud VM: Ubuntu 24.04.5 LTS, Linux 6.18, x86_64, 2 vCPUs, about 7 GB RAM, system CPython 3.13.18 with pip 26.2. uv 0.13.9 was installed from its PyPI wheel into a fresh virtual environment with pip install uv==0.13.9, and uv's cache, data and tool directories were pointed at an empty scratch location so nothing pre-existing could help. Timings are single-machine wall-clock figures and only indicative.
Install footprint
| Measure | Result |
|---|---|
| Wheel | uv-0.13.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl, 17.6 MB |
Binaries placed in bin/ | uv 38,409,000 bytes and uvx 331,344 bytes; the Python package itself is a 16 KB shim |
Dynamic libraries (ldd) | glibc only (libc, libm, libgcc_s, libpthread, libdl, librt) |
uv --version | uv 0.13.9 (x86_64-unknown-linux-gnu) |
Project workflow
| Command | Observed |
|---|---|
uv python install 3.12 | Downloaded cpython-3.12.16-linux-x86_64-gnu (33.1 MiB), "Installed Python 3.12.16 in 1.44s"; 105 MB on disk |
uv init demo | Packaged application layout: src/demo/__init__.py, [project.scripts] entry, uv_build>=0.13.9,<0.14.0 build backend, a .gitignore, a fresh Git repository and .python-version set to 3.12 |
uv add fastapi requests | Created .venv, "Resolved 16 packages in 458ms", "Prepared 16 packages in 4.12s", "Installed 16 packages in 6ms"; 4.6 s total. pyproject.toml gained fastapi>=0.164.0 and requests>=2.34.2 |
uv run demo | Hello from demo! |
uv lock / uv lock --check with nothing changed | "Resolved 16 packages in 1ms" / exit code 0 |
uv sync | "Checked 16 packages in 0.23ms" |
uv run python -c pass vs .venv/bin/python -c pass | about 21.6 ms vs 11.7 ms over three runs; --no-sync about 19.5 ms |
Hand-edit pyproject.toml, then uv sync --locked | "The lockfile at uv.lock needs to be updated, but --locked was provided.", exit code 1 |
.venv size | 13 MB, pyvenv.cfg records uv = 0.13.9 |
The init default is worth noting: the docs say that before v0.12 applications were created without a build system, while 0.13.9 creates a src-layout package with the uv_build backend. --no-package or --bare gives the older flat style. The .python-version pin came out as 3.12 even though the system had 3.13, because the managed 3.12.16 installed a moment earlier wins under the default managed preference.
What the lockfile contains
| Property | Value |
|---|---|
| Size | 85,072 bytes, 410 lines, for 16 packages (FastAPI, Requests and their dependencies, including Pydantic 2.14.3) |
| Header | version = 1, revision = 5, requires-python = ">=3.12" |
| Hashes | 249 sha256 entries, each with file size and upload-time |
| Platform coverage | 98 separate pydantic_core wheel URLs recorded, one per platform and Python tag |
| Project entry | source = { editable = "." } |
That last pair of rows is the universal lockfile in practice: one compiled dependency accounts for most of the file, because uv records every wheel any platform could need. Expect large diffs on upgrades.
Install timings against pip
The same four requirements (fastapi requests rich pandas, resolving to 23 packages including pandas 3.1.1 and NumPy 2.5.5) were installed into new Python 3.13.18 environments, with uv venv plus uv pip install on one side and python -m venv plus pip 26.2.2 on the other. "Cold" means an empty tool cache; "warm" means a new environment with the cache already filled. The VM's pip configuration had bytecode compilation turned off, matching uv's default.
| Step | uv 0.13.9 | pip 26.2.2 + venv |
|---|---|---|
| Create environment | 0.05 s | 1.85 s (python -m venv also installs pip) |
| Cold install, three runs | 1.15 s, 2.03 s, 3.47 s | 26.77 s, 8.69 s, 6.15 s |
| Warm install | 0.11 s, 0.11 s, 0.10 s | 3.59 s, 1.89 s |
Warm, --link-mode=copy | 0.47 s | - |
Warm, --compile-bytecode | 6.86 s | - |
| Cache size after install | 130 MB (unpacked wheels) | 38 MB (compressed downloads) |
On the first cold uv run the output broke down as "Resolved 23 packages in 738ms", "Prepared 23 packages in 323ms", "Installed 23 packages in 28ms". The first pip cold run was slowed by the network; later cold runs give a fairer picture of roughly 2 to 4 times faster for uv here, against 17 to 35 times for warm installs. Two qualifications matter. First, much of the warm speed comes from hardlinking: a NumPy file in the new environment had a link count of 2, shared with the cache, while copy mode quadrupled the time. Second, compiling bytecode, which the Docker guide recommends for production images, dominated everything at 6.86 s. The README's "10-100x faster than pip" figure comes from BENCHMARKS.md, which uses Trio's documentation requirements on macOS and warns that results "may vary dramatically" by filesystem and package set.
Tools, scripts and interpreters
| Command | Observed |
|---|---|
uvx ruff --version, first and second run | 0.82 s (downloaded ruff, 10.1 MiB) then 0.02 s; ruff 0.17.5 |
uvx ruff check src on a file with import os,sys | I001 and two F401 findings, "3 fixable with --fix" |
uv tool install ruff | 0.02 s from cache, "Installed 1 executable: ruff", a symlink in the user bin directory and a warning that the directory was not on PATH |
uvx pycowsay 'hello world!' | Worked, but printed SyntaxWarning: invalid escape sequence '\ ' from the package |
uv add --script example.py httpx rich | Wrote a /// script block with requires-python = ">=3.12", httpx>=0.28.1 and rich>=15.0.0 |
uv run example.py, first and second run | 0.85 s (11 packages installed) then 0.18 s |
uv lock --script example.py | Created example.py.lock, 8,243 bytes |
Script with requires-python = ">=3.14" | uv downloaded cpython-3.15.2 (36.6 MiB) on the fly and printed 3.15.2; 1.41 s |
Script with exclude-newer = "2024-01-01T00:00:00Z" | Resolved requests 2.31.0 instead of 2.34.2 |
uv pip compile requirements.in (fastapi, requests) | 0.08 s, 45-line requirements.txt; with --generate-hashes 383 lines; -o pylock.toml gave a 99-line file with lock-version = "1.0" and created-by = "uv" |
uv python list | 31 rows: CPython 3.8 to 3.16.0a2 (plus free-threaded builds), PyPy 3.8 to 3.12 and GraalPy 3.10 to 3.13 as downloads, and the system's 3.13.18, 3.12.3 and 3.11.18 interpreters |
The pycowsay warning is the behaviour the pip-compatibility guide describes: uv does not compile bytecode by default, so some SyntaxWarning messages that pip's compile step would hide show up at run time.
Workspace, build and cache
uv init --lib packages/coreinside the project addedmembers = ["packages/core"]to a new[tool.uv.workspace]table;uv add corewrotecore = { workspace = true }, and the shared lockfile grew to 17 packages.uv build --all-packagesproduced a wheel and an sdist for both members (each file under 1.5 KB) in about 0.02 s.- At the end of the session
uv cache sizereported 58.9 MiB.uv cache prune --cireported "Removed 2483 files (12.1MiB)" anddufell from 59 MB to 8.8 MB; the gap reflects hardlinks, which the docs say the default estimate does not account for. The next sync downloadedpydantic-coreagain, as expected after pre-built wheels are pruned.
Gotchas found
- With the pip-installed uv's virtual environment first on
PATHand no other environment active,uv pip install requestsreported "Using Python 3.13.18 environment at" that tool environment and installed into it. With a cleanPATHthe same command stopped with "No virtual environment found; runuv venvto create an environment, or pass--system". uv self updateon a PyPI install fails with "Self-update is only available for uv binaries installed via the standalone installation scripts."uv initin a directory that already haspyproject.tomlstops with an error rather than merging.
uv in Docker and CI
The Docker guide recommends copying the static binary out of the distroless image and pinning a version:
COPY --from=ghcr.io/astral-sh/uv:0.13.9 /uv /uvx /bin/
For faster rebuilds it installs dependencies in a separate layer, binding only the lockfile, then copies the source and syncs again:
RUN --mount=type=cache,target=/root/.cache/uv \
--mount=type=bind,source=uv.lock,target=uv.lock \
uv sync --frozen --no-install-project
The guide also suggests ENV UV_COMPILE_BYTECODE=1 for production images, UV_LINK_MODE=copy when the cache mount is on another filesystem, and adding .venv to .dockerignore.
For GitHub Actions the docs point to astral-sh/setup-uv, which can persist the cache:
- name: Enable caching
uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
with:
enable-cache: true
Typical steps are uv sync --locked --all-extras --dev and uv run pytest tests. When managing the cache manually, the docs recommend ending the job with uv cache prune --ci, because re-downloading pre-built wheels is "often faster" than restoring them, while wheels built from source are worth keeping. For pre-commit style checks in the same pipelines, the Rust rewrite trend that produced uv and Ruff also includes hook runners such as prek.
Use cases
- Application repositories. A FastAPI service with
uv.lockcommitted,uv sync --lockedin CI and the Docker layer pattern above. - Monorepos. A workspace with a core library, a CLI and plugins sharing one lockfile, as the workspace docs describe.
- Speeding up pip-tools pipelines. Replacing
pip-compileandpip-syncwithuv pip compileanduv pip syncwithout changing file formats. - Self-contained scripts. Ops and data scripts with PEP 723 headers and a
#!/usr/bin/env -S uv run --scriptshebang, optionally pinned withexclude-newer. - Interpreter management. Testing against several CPython versions, or free-threaded builds, without pyenv or system packages.
How uv compares
uv overlaps with several single-purpose tools. Feature descriptions below come from each project's README or PyPI metadata as fetched on 18 November 2026; apart from pip, none were benchmarked here.
| Tool | What it says it does | Lockfile | Manages Python itself | Latest (PyPI) | Licence |
|---|---|---|---|---|---|
| uv | Package and project manager, tool runner, Python installer | uv.lock (universal); can export pylock.toml | Yes | 0.13.9 (17 Nov 2026) | MIT OR Apache-2.0 |
| pip + venv | "The PyPA recommended tool for installing Python packages" | None built in | No | pip 26.3 (2 Nov 2026) | MIT |
| pip-tools | "pip-compile + pip-sync"; installed into each project's virtual environment | Pinned requirements.txt | No | 7.7.0 (16 Nov 2026) | BSD-3-Clause |
| Poetry | "Python packaging and dependency management made easy" with a pyproject.toml project format | poetry.lock | Not in README scope | 2.5.1 (20 Sep 2026) | MIT |
| pipx | "Install and Run Python Applications in Isolated Environments" | - | No | 1.18.19 (17 Nov 2026) | MIT |
| pyenv | "Simple Python Version Management", pure shell scripts with shims; does not manage virtualenvs | - | Yes (pyenv install; uv's docs note it builds from source) | Not on PyPI | MIT |
| PDM | "A modern Python package and dependency manager supporting the latest PEP standards", with plug-ins | pdm.lock | Yes, via python-build-standalone | 2.29.7 (6 Nov 2026) | MIT |
| Pixi | "Cross-platform, multi-language package manager" built on the conda ecosystem, with PyPI integration | Always-updated lock file | Through conda packages | Not on PyPI | BSD-3-Clause |
The practical split: pip, pip-tools, pipx and pyenv each do one job, and many teams combine them; uv aims to cover all four with one binary and one cache. Poetry and PDM are the closest project-manager peers, both written in Python with their own lockfiles; the PDM README notes it can install Pythons using Astral's python-build-standalone, the same project uv's docs name as the source of its managed CPython builds. Pixi is the better comparison when a project needs non-Python binaries from conda-forge, such as C++ or R toolchains, since uv only installs Python packages from Python indexes.
Limits and when not to use it
- Not an exact pip clone. The compatibility guide lists many deliberate differences: PEP 517 build isolation by default (some old sdists fail without
--no-build-isolation), no reading ofpip.conforPIP_INDEX_URL, first-index-wins for multiple indexes, stricter spec enforcement, noeggsupport and no bytecode compilation unless asked. - Breaking changes in minor versions. uv is still 0.x and, per its versioning policy, bumps the minor version for breaking changes. 0.13.0 (9 October 2026) switched the default downloaded Python to 3.15, began honouring
--require-hashesin included constraint files and changed the cache format, so the first runs after an upgrade may re-download. Pin uv in CI and Docker, and pinuv_buildwith an upper bound asuv initdoes. - Lockfile lock-in.
uv.lockcannot be read by other tools, and its schema can only change in a minor release. Patch releases within a minor line are guaranteed compatible; across minor lines a newer uv may be required. - Disk and filesystem behaviour. The cache stores unpacked wheels (130 MB against pip's 38 MB in the test above) and relies on hardlinks or reflinks for speed. Put the cache on the same filesystem as the environments, and on non-ephemeral CI runners expect it to grow; the GitHub guide warns the default cache directory "can grow unbounded".
- Automatic interpreter downloads. Convenient on a laptop, surprising in locked-down environments: a script asking for Python 3.14 silently pulled 36.6 MiB of CPython 3.15.2 in the test. Set
python-downloads = "manual"or pass--no-python-downloadswhere that matters, and uninstalling a managed Python breaks tool environments that used it. - Universal resolution can be stricter. Every dependency must support the full
requires-pythonrange, so a project declaring>=3.8can fail to lock where a platform-specific pip install would succeed. - Workspaces need compatible members. The docs say workspaces are "not suited for cases in which members have conflicting requirements"; use path dependencies instead.
- Vendor concentration. uv, its build backend, the Python distributions it downloads and the GitHub Action are all maintained by one company. The dual permissive licence keeps forking possible, but teams that weigh governance should factor it in.
- Platform tiers. Only macOS (Apple Silicon and x86_64), Linux x86_64 and Windows x86_64 are Tier 1. Linux aarch64 and Windows arm64 are Tier 2 ("guaranteed to build", test suite not run), FreeBSD is Tier 3, and macOS 13 or later is required.
Release cadence and documentation notes
PyPI lists 333 uv releases since 0.0.5 on 15 February 2024, 91 of them in 2026. Minor lines have come every two to five months: 0.10.0 on 5 February, 0.11.0 on 23 March, 0.12.0 on 28 July and 0.13.0 on 9 October 2026. Patch releases arrive roughly weekly; the three most recent were 0.13.7 on 3 November, 0.13.8 on 12 November and 0.13.9 on 17 November. The 0.13.9 changelog adds preview support for PEP 832 .venv redirect files, shrinks lockfiles by factoring repeated environment markers, and rejects wheels that an index advertises under a different package name. Recent releases also carry preview work on wheel variants and a preview uv audit command.
Documentation lives in the repository's docs/ folder and is published at docs.astral.sh/uv. A few details came up while cross-checking it. The project-init page shows the build requirement as uv_build>=0.13.9,<0.14 while 0.13.9 actually writes <0.14.0, which is equivalent. The settings and environment-variable references are generated at build time and are not present as raw files in the repository, so they have to be read on the docs site or through uv help.
Project activity
Checked 18 November 2026: latest release uv 0.13.9 (released 17 November 2026, per the changelog), dual MIT or Apache-2.0 licence, about 92,100 stars on the astral-sh/uv repository (92,135 at the time of writing) with about 3,900 forks and a push on the day of checking. The project is written in Rust, was created on 2 October 2023 and develops on main. Documentation is at docs.astral.sh/uv, and the README links a Discord server for questions. The README's FAQ answers "Is uv ready for production?" with "Yes, uv is stable and widely used in production", pointing to the versioning policy for what that promise covers.
Enjoying this project?
Discover more amazing open-source projects on TechLogHub. We curate the best developer tools and projects.
Repository:https://github.com/astral-sh/uv
GitHub - astral-sh/uv: uv: Fast Python Package and Project Manager in Rust
uv is Astral's Rust-written Python package and project manager, dual-licensed MIT or Apache-2.0. Version 0.13.9 tested on Linux: projects, uv.lock, uvx, inline ...
github - astral-sh/uv
Related Projects
Maintain uv: Fast Python Package and Project Manager in Rust? Add the badge to your README
Show that the project is featured on TechLogHub and send readers to this write-up.
[](https://techloghub.com/open-source/uv-python-package-manager?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)