Package: uv
uvAn extremely fast Python package installer and resolver, written in Rust. Designed as a drop-in
replacement forpipandpip-compile.uv is backed byAstral, the creators ofRuff.Highlights⚖️ Drop-in replacement for commonpip,pip-tools, andvirtualenvcommands.⚡️10-100x fasterthanpipandpip-tools(pip-compileandpip-sync).💾 Disk-space efficient, with a global cache for dependency deduplication.🐍 Installable viacurl,pip,pipx, etc. uv is a static binary that can be installed
without Rust or Python.🧪 Tested at-scale against the top 10,000 PyPI packages.🖥️ Support for macOS, Linux, and Windows.🧰 Advanced features such asdependency version overridesandalternative resolution strategies.⁉️ Best-in-class error messages with a conflict-tracking resolver.🤝 Support for a wide range of advancedpipfeatures, including editable installs, Git
dependencies, direct URL dependencies, local dependencies, constraints, source distributions,
HTML and JSON indexes, and more.Getting StartedInstall uv with our standalone installers, or fromPyPI:# On macOS and Linux.curl-LsSfhttps://astral.sh/uv/install.sh|sh# On Windows.powershell-c"irm https://astral.sh/uv/install.ps1 | iex"# With pip.pipinstalluv# With pipx.pipxinstalluv# With Homebrew.brewinstalluv# With Pacman.pacman-SuvTo create a virtual environment:uvvenv# Create a virtual environment at .venv.To activate the virtual environment:# On macOS and Linux.source.venv/bin/activate# On Windows..venv\Scripts\activateTo install a package into the virtual environment:uvpipinstallflask# Install Flask.uvpipinstall-rrequirements.txt# Install from a requirements.txt file.uvpipinstall-e.# Install the current project in editable mode.uvpipinstall"package @ ."# Install the current project from diskuvpipinstall"flask[dotenv]"# Install Flask with "dotenv" extra.To generate a set of locked dependencies from an input file:uvpipcompilepyproject.toml-orequirements.txt# Read a pyproject.toml file.uvpipcompilerequirements.in-orequirements.txt# Read a requirements.in file.To sync a set of locked dependencies with the virtual environment:uvpipsyncrequirements.txt# Install from a requirements.txt file.uv'spip-installandpip-compilecommands support many of the same command-line arguments
as existing tools, including-r requirements.txt,-c constraints.txt,-e .(for editable
installs),--index-url, and more.Limitationsuv does not support the entirepipfeature set. Namely, uv does not (and does not plan to)
support the followingpipfeatures:.eggdependenciesEditable installs for Git and direct URL dependencies (editable installsaresupported for local
dependencies)On the other hand, uv plans to (but does not currently) support:Hash-checking modeURL requirements without package names(e.g.,https://...instead ofpackage @ https://...)Likepip-compile, uv generates a platform-specificrequirements.txtfile (unlike, e.g.,poetryandpdm, which generate platform-agnosticpoetry.lockandpdm.lockfiles). As such,
uv'srequirements.txtfiles may not be portable across platforms and Python versions.Roadmapuv is an extremely fast Python package resolver and installer, designed as a drop-in
replacement forpip,pip-tools(pip-compileandpip-sync), andvirtualenv.uv represents an intermediary goal in our pursuit of a"Cargo for Python":
a comprehensive project and package manager that is extremely fast, reliable, and easy to use.Think: a single binary that bootstraps your Python installation and gives you everything you need to
be productive with Python, bundling not onlypip,pip-tools, andvirtualenv, but alsopipx,tox,poetry,pyenv,ruff, and more.Our goal is to evolve uv into such a tool.In the meantime, though, the narrowerpip-toolsscope allows us to solve the low-level problems
involved in building such a tool (like package installation) while shipping something immediately
useful with a minimal barrier to adoption.Advanced UsagePython discoveryuv itself does not depend on Python, but it does need to locate a Python environment to (1)
install dependencies into the environment and (2) build source distributions.When runningpip syncorpip install, uv will search for a virtual environment in the
following order:An activated virtual environment based on theVIRTUAL_ENVenvironment variable.An activated Conda environment based on theCONDA_PREFIXenvironment variable.A virtual environment at.venvin the current directory, or in the nearest parent directory.If no virtual environment is found, uv will prompt the user to create one in the current
directory viauv venv.When runningpip compile, uv does notrequirea virtual environment and will search for a
Python interpreter in the following order:An activated virtual environment based on theVIRTUAL_ENVenvironment variable.An activated Conda environment based on theCONDA_PREFIXenvironment variable.A virtual environment at.venvin the current directory, or in the nearest parent directory.The Python interpreter available aspython3on macOS and Linux, orpython.exeon Windows.If a--python-versionis provided topip compile(e.g.,--python-version=3.7), uv will
search for a Python interpreter matching that version in the following order:An activated virtual environment based on theVIRTUAL_ENVenvironment variable.An activated Conda environment based on theCONDA_PREFIXenvironment variable.A virtual environment at.venvin the current directory, or in the nearest parent directory.The Python interpreter available as, e.g.,python3.7on macOS and Linux. On Windows, uv
will use the same mechanism aspy --list-pathsto discover all available Python interpreters,
and will select the first interpreter matching the requested version.The Python interpreter available aspython3on macOS and Linux, orpython.exeon Windows.Since uv has no dependency on Python, it can even install into virtual environments other than
its own. For example, settingVIRTUAL_ENV=/path/to/venvwill cause uv to install into/path/to/venv, no matter where uv is installed.Finally, uv can also install into non-virtual environments by providing a--pythonargument touv pip syncoruv pip install. For example,uv pip install --python=/path/to/pythonwill
install into the environment linked to the/path/to/pythoninterpreter.For convenience,uv pip install --systemwill install into the system Python environment, as an
approximate shorthand for, e.g.,uv pip install --python=$(which python3). Though we generally
recommend the use of virtual environments for dependency management,--systemis intended to
enable the use ofuvin continuous integration and containerized environments.Git authenticationuv allows packages to be installed from Git and supports the following schemes for authenticating with private
repositories.Using SSH:git+ssh://git@<hostname>/...(e.g.git+ssh://git@github.com/astral-sh/uv)git+ssh://git@<host>/...(e.g.git+ssh://git@github.com-key-2/astral-sh/uv)See theGitHub SSH documentationfor more details on how to configure SSH.Using a password or token:git+https://<user>:<token>@<hostname>/...(e.g.git+https://git:github_pat_asdf@github.com/astral-sh/uv)git+https://<token>@<hostname>/...(e.g.git+https://github_pat_asdf@github.com/astral-sh/uv)git+https://<user>@<hostname>/...(e.g.git+https://git@github.com/astral-sh/uv)When using a GitHub personal access token, the username is arbitrary. GitHub does not support logging in with password directly, although other hosts may. If a username is provided without credentials, you will be prompted to enter them.If there are no credentials present in the URL and authentication is needed, theGit credential helperwill be queried.Dependency cachinguv uses aggressive caching to avoid re-downloading (and re-building dependencies) that have
already been accessed in prior runs.The specifics of uv's caching semantics vary based on the nature of the dependency:For registry dependencies(like those downloaded from PyPI), uv respects HTTP caching headers.For direct URL dependencies, uv respects HTTP caching headers, and also caches based on
the URL itself.For Git dependencies, uv caches based on the fully-resolved Git commit hash. As such,uv pip compilewill pin Git dependencies to a specific commit hash when writing the resolved
dependency set.For local dependencies, uv caches based on the last-modified time of thesetup.pyorpyproject.tomlfile.If you're running into caching issues, uv includes a few escape hatches:To force uv to revalidate cached data for all dependencies, runuv pip install --refresh ....To force uv to revalidate cached data for a specific dependency, run, e.g.,uv pip install --refresh-package flask ....To force uv to ignore existing installed versions, runuv pip install --reinstall ....To clear the global cache entirely, runuv cache clean.Resolution strategyBy default, uv follows the standard Python dependency resolution strategy of preferring the
latest compatible version of each package. For example,uv pip install flask>=2.0.0will
install the latest version of Flask (at time of writing:3.0.0).However, uv's resolution strategy can be configured to support alternative workflows. With--resolution=lowest, uv will install thelowestcompatible versions for all dependencies,
bothdirectandtransitive. Alternatively,--resolution=lowest-directwill opt for thelowestcompatible versions for alldirectdependencies, while using thelatestcompatible versions for alltransitivedependencies. This distinction can be particularly useful
for library authors who wish to test against the lowest supported versions of direct dependencies
without restricting the versions of transitive dependencies.For example, given the followingrequirements.infile:flask>=2.0.0Runninguv pip compile requirements.inwould produce the followingrequirements.txtfile:# This file was autogenerated by uv via the following command:
#    uv pip compile requirements.in
blinker==1.7.0
    # via flask
click==8.1.7
    # via flask
flask==3.0.0
itsdangerous==2.1.2
    # via flask
jinja2==3.1.2
    # via flask
markupsafe==2.1.3
    # via
    #   jinja2
    #   werkzeug
werkzeug==3.0.1
    # via flaskHowever,uv pip compile --resolution=lowest requirements.inwould instead produce:# This file was autogenerated by uv via the following command:
#    uv pip compile requirements.in --resolution=lowest
click==7.1.2
    # via flask
flask==2.0.0
itsdangerous==2.0.0
    # via flask
jinja2==3.0.0
    # via flask
markupsafe==2.0.0
    # via jinja2
werkzeug==2.0.0
    # via flaskPre-release handlingBy default, uv will accept pre-release versions during dependency resolution in two cases:If the package is a direct dependency, and its version markers include a pre-release specifier
(e.g.,flask>=2.0.0rc1).Ifallpublished versions of a package are pre-releases.If dependency resolution fails due to a transitive pre-release, uv will prompt the user to
re-run with--prerelease=allow, to allow pre-releases for all dependencies.Alternatively, you can add the transitive dependency to yourrequirements.infile with
pre-release specifier (e.g.,flask>=2.0.0rc1) to opt in to pre-release support for that specific
dependency.Pre-releases arenotoriously difficultto model, and are a frequent source of bugs in other packaging tools. uv's pre-release handling
isintentionallylimited andintentionallyrequires user intervention to opt in to pre-releases
to ensure correctness, though pre-release handling will be revisited in future releases.Dependency overridesHistorically,piphas supported "constraints" (-c constraints.txt), which allows users to
narrow the set of acceptable versions for a given package.uv supports constraints, but also takes this concept further by allowing users tooverridethe
acceptable versions of a package across the dependency tree via overrides (--override overrides.txt).In short, overrides allow the user to lie to the resolver by overriding the declared dependencies
of a package. Overrides are a useful last resort for cases in which the user knows that a
dependency is compatible with a newer version of a package than the package declares, but the
package has not yet been updated to declare that compatibility.For example, if a transitive dependency declarespydantic>=1.0,<2.0, but the user knows that
the package is compatible withpydantic>=2.0, the user can override the declared dependency
withpydantic>=2.0,<3to allow the resolver to continue.While constraints are purelyadditive, and thus cannotexpandthe set of acceptable versions for
a package, overridescanexpand the set of acceptable versions for a package, providing an escape
hatch for erroneous upper version bounds.Multi-version resolutionuv'spip-compilecommand produces a resolution that's known to be compatible with the
current platform and Python version. Unlike Poetry, PDM, and other package managers, uv does
not yet produce a machine-agnostic lockfile.However, uvdoessupport resolving for alternate Python versions via the--python-versioncommand line argument. For example, if you're running uv on Python 3.9, but want to resolve for
Python 3.8, you can runuv pip compile --python-version=3.8 requirements.into produce a
Python 3.8-compatible resolution.Platform supportuv has Tier 1 support for the following platforms:macOS (Apple Silicon)macOS (x86_64)Linux (x86_64)Windows (x86_64)uv is continuously built, tested, and developed against its Tier 1 platforms. Inspired by the
Rust project, Tier 1 can be thought of as"guaranteed to work".uv has Tier 2 support ("guaranteed to build") for the following platforms:Linux (PPC64)Linux (PPC64LE)Linux (aarch64)Linux (armv7)Linux (i686)Linux (s390x)uv ships pre-built wheels toPyPIfor its Tier 1 and
Tier 2 platforms. However, while Tier 2 platforms are continuously built, they are not continuously
tested or developed against, and so stability may vary in practice.Beyond the Tier 1 and Tier 2 platforms, uv is known to build on i686 Windows, and knownnotto build on aarch64 Windows, but does not consider either platform to be supported at this time.uv supports and is tested against Python 3.8, 3.9, 3.10, 3.11, and 3.12.Acknowledgementsuv's dependency resolver usesPubGrubunder the hood.
We're grateful to the PubGrub maintainers, especiallyJacob Finkelman,
for their support.uv's Git implementation is based onCargo.Some of uv's optimizations are inspired by the great work we've seen inpnpm,Orogene, andBun. We've also learned a lot from Nathaniel
J. Smith'sPosyand adapted itstrampolinefor Windows support.Licenseuv is licensed under either ofApache License, Version 2.0, (LICENSE-APACHEorhttps://www.apache.org/licenses/LICENSE-2.0)MIT license (LICENSE-MITorhttps://opensource.org/licenses/MIT)at your option.Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in uv by you, as defined in the Apache-2.0 license, shall be
dually licensed as above, without any additional terms or conditions.