An extremely fast Python package installer and resolver, written in Rust. Designed as a drop-in replacement for common pip and pip-tools workflows.
一个极快的 Python 软件包安装程序和解析器，用 Rust 编写。设计为常见 pip 和 pip-tools 工作流的即插即用替代品。

Installing the Trio dependencies with a warm cache.
使用热缓存安装 Trio 依赖项。

• ⚖️ Drop-in replacement for common pip, pip-tools, and virtualenv commands.
  ⚖️ 用于常见 pip 、 pip-tools 和 virtualenv 命令的即插即用替代品。
• ⚡️ 10-100x faster than pip and pip-tools (pip-compile and pip-sync).
  ⚡️ 比 pip 和 pip-tools ( pip-compile 和 pip-sync ) 快 10-100 倍。
• 💾 Disk-space efficient, with a global cache for dependency deduplication.
  💾 磁盘空间利用率高，具有用于依赖项去重的全局缓存。
• 🐍 Installable via curl, pip, pipx, etc. uv is a static binary that can be installed without Rust or Python.
  🐍 可通过 curl 、 pip 、 pipx 等方式安装。uv 是一个静态二进制文件，无需安装 Rust 或 Python。
• 🧪 Tested at-scale against the top 10,000 PyPI packages.
  🧪 针对前 10,000 个 PyPI 软件包进行了大规模测试。
• 🖥️ Support for macOS, Linux, and Windows.
  🖥️ 支持 macOS、Linux 和 Windows。
• 🧰 Advanced features such as dependency version overrides and alternative resolution strategies.
  🧰 高级功能，如依赖版本覆盖和替代解析策略。
• ⁉️ Best-in-class error messages with a conflict-tracking resolver.
  ⁉️ 具有冲突跟踪解析器的最佳错误消息。
• 🤝 Support for a wide range of advanced pip features, including editable installs, Git dependencies, direct URL dependencies, local dependencies, constraints, source distributions, HTML and JSON indexes, and more.
  🤝 支持广泛的高级 pip 功能，包括可编辑安装、Git 依赖项、直接 URL 依赖项、本地依赖项、约束、源分发、HTML 和 JSON 索引等。

uv is backed by Astral, the creators of Ruff.
uv 由 Ruff 的创始人 Astral 支持。

Install uv with our standalone installers, or from PyPI:
使用我们的独立安装程序安装 uv，或从 PyPI 安装：

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# With pip.
pip install uv

# With pipx.
pipx install uv

# With Homebrew.
brew install uv

# With Pacman.
pacman -S uv

To create a virtual environment:
创建虚拟环境：

uv venv  # Create a virtual environment at .venv.

To activate the virtual environment:
激活虚拟环境：

# On macOS and Linux.
source .venv/bin/activate

# On Windows.
.venv\Scripts\activate

To install a package into the virtual environment:
将软件包安装到虚拟环境中：

uv pip install flask                # Install Flask.
uv pip install -r requirements.txt  # Install from a requirements.txt file.
uv pip install -e .                 # Install the current project in editable mode.
uv pip install "package @ ."        # Install the current project from disk.
uv pip install "flask[dotenv]"      # Install Flask with "dotenv" extra.

To generate a set of locked dependencies:
生成一组锁定的依赖项：

uv pip compile requirements.in -o requirements.txt    # Read a requirements.in file.
uv pip compile pyproject.toml -o requirements.txt     # Read a pyproject.toml file.
uv pip compile setup.py -o requirements.txt           # Read a setup.py file.
echo flask | uv pip compile - -o requirements.txt     # Read from stdin.
uv pip freeze | uv pip compile - -o requirements.txt  # Lock the current environment.

To sync a set of locked dependencies with the virtual environment:
将一组锁定的依赖项与虚拟环境同步：

uv pip sync requirements.txt  # Install from a requirements.txt file.

uv's pip-install and pip-compile commands 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.
uv 的 pip-install 和 pip-compile 命令支持许多与现有工具相同的命令行参数，包括 -r requirements.txt ， -c constraints.txt ， -e . （用于可编辑安装）， --index-url 等等。

While uv supports a large subset of the pip interface, it does not support the entire feature set. In some cases, those differences are intentional; in others, they're a result of uv's early stage of development.
虽然 uv 支持 pip 接口的大部分子集，但不支持整个功能集。在某些情况下，这些差异是有意的；在其他情况下，这是 uv 开发早期的结果。

For details, see our pip compatibility guide.
有关详细信息，请参阅我们的 pip 兼容性指南。

Like pip-compile, uv generates a platform-specific requirements.txt file (unlike, e.g., poetry and pdm, which generate platform-agnostic poetry.lock and pdm.lock files). As such, uv's requirements.txt files may not be portable across platforms and Python versions.
像 pip-compile 一样，uv 会生成特定于平台的 requirements.txt 文件（不像，例如， poetry 和 pdm ，它们生成与平台无关的 poetry.lock 和 pdm.lock 文件）。因此，uv 的 requirements.txt 文件可能无法跨平台和 Python 版本移植。

uv is an extremely fast Python package resolver and installer, designed as a drop-in replacement for pip, pip-tools (pip-compile and pip-sync), and virtualenv.
uv 是一个极快的 Python 包解析器和安装程序，旨在作为 pip ， pip-tools （ pip-compile 和 pip-sync ）以及 virtualenv 的即插即用替代品。

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.
uv 代表我们追求“Python 货物”的中间目标：一个综合的项目和包管理器，极其快速、可靠且易于使用。

Think: a single binary that bootstraps your Python installation and gives you everything you need to be productive with Python, bundling not only pip, pip-tools, and virtualenv, but also pipx, tox, poetry, pyenv, ruff, and more.
想象一下：一个单一的二进制文件，引导您的 Python 安装，并为您提供一切您需要以 Python 高效工作的工具，不仅捆绑了 pip ， pip-tools 和 virtualenv ，还有 pipx ， tox ， poetry ， pyenv ， ruff ，以及更多。

Our goal is to evolve uv into such a tool.
我们的目标是将 uv 发展成这样一个工具。

In the meantime, though, the narrower pip-tools scope 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.
与此同时，较窄的 pip-tools 范围使我们能够解决构建此类工具（如软件包安装）涉及的低级问题，同时以最小的采用障碍立即提供可用的东西。

uv 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.
uv 本身不依赖于 Python，但它需要定位 Python 环境来（1）将依赖项安装到环境中，以及（2）构建源分发。

When running pip sync or pip install, uv will search for a virtual environment in the following order:

• An activated virtual environment based on the VIRTUAL_ENV environment variable.
• An activated Conda environment based on the CONDA_PREFIX environment variable.
• A virtual environment at .venv in 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 via uv venv.

When running pip compile, uv does not require a virtual environment and will search for a Python interpreter in the following order:

• An activated virtual environment based on the VIRTUAL_ENV environment variable.
• An activated Conda environment based on the CONDA_PREFIX environment variable.
• A virtual environment at .venv in the current directory, or in the nearest parent directory.
• The Python interpreter available as python3 on macOS and Linux, or python.exe on Windows.

If a --python-version is provided to pip 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 the VIRTUAL_ENV environment variable.
• An activated Conda environment based on the CONDA_PREFIX environment variable.
• A virtual environment at .venv in the current directory, or in the nearest parent directory.
• The Python interpreter available as, e.g., python3.7 on macOS and Linux.
• The Python interpreter available as python3 on macOS and Linux, or python.exe on Windows.
• On Windows, the Python interpreter returned by py --list-paths that matches the requested version.

Since uv has no dependency on Python, it can even install into virtual environments other than its own. For example, setting VIRTUAL_ENV=/path/to/venv will cause uv to install into /path/to/venv, no matter where uv is installed.

uv can also install into arbitrary, even non-virtual environments by providing a --python argument to uv pip sync or uv pip install. For example, uv pip install --python=/path/to/python will install into the environment linked to the /path/to/python interpreter.

For convenience, uv pip install --system will 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, --system is intended to enable the use of uv in continuous integration and containerized environments.

Installing into system Python across platforms and distributions is notoriously difficult. uv supports the common cases, but will not work in all cases. For example, installing into system Python on Debian prior to Python 3.10 is unsupported due to the distribution's patching of distutils (but not sysconfig). While we always recommend the use of virtual environments, uv considers them to be required in these non-standard environments.

uv 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 the GitHub SSH documentation for 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, the Git credential helper will be queried.

uv supports credentials over HTTP when querying package registries.

Authentication can come from the following sources, in order of precedence:

• The URL, e.g., https://<user>:<password>@<hostname>/...
• A netrc configuration file
• A keyring provider (requires opt-in)

If authentication is found for a single net location (scheme, host, and port), it will be cached for the duration of the command and used for other queries to that net location. Authentication is not cached across invocations of uv.

Note --keyring-provider subprocess or UV_KEYRING_PROVIDER=subprocess must be provided to enable keyring-based authentication.

Authentication may be used for hosts specified in the following contexts:

• index-url
• extra-index-url
• find-links
• package @ https://...

See the pip compatibility guide for details on differences from pip.

uv 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 compile will 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 the source archive (i.e., the local .whl or .tar.gz file). For directories, uv caches based on the last-modified time of the pyproject.toml, setup.py, or setup.cfg file.

It's safe to run multiple uv commands concurrently, even against the same virtual environment. uv's cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent readers and writers. uv applies a file-based lock to the target virtual environment when installing, to avoid concurrent modifications across processes.

Note that it's not safe to modify the uv cache directly (e.g., uv cache clean) while other uv commands are running, and never safe to modify the cache directly (e.g., by removing a file or directory).

If you're running into caching issues, uv includes a few escape hatches:

• To force uv to revalidate cached data for all dependencies, run uv 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, run uv pip install --reinstall ....
• To clear the global cache entirely, run uv cache clean.

By 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.0 will 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 the lowest compatible versions for all dependencies, both direct and transitive. Alternatively, --resolution=lowest-direct will opt for the lowest compatible versions for all direct dependencies, while using the latest compatible versions for all transitive dependencies. 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 following requirements.in file:

flask>=2.0.0

Running uv pip compile requirements.in would produce the following requirements.txt file:

# 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 flask

However, uv pip compile --resolution=lowest requirements.in would 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 flask

By default, uv will accept pre-release versions during dependency resolution in two cases:
默认情况下，uv 在两种情况下在依赖解析期间接受预发布版本：

1. If the package is a direct dependency, and its version markers include a pre-release specifier (e.g., flask>=2.0.0rc1).
   如果包是直接依赖项，并且其版本标记包含预发布说明符（例如， flask>=2.0.0rc1 ）。
2. If all published 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.
如果由于传递性预发布而导致依赖关系解析失败，uv 将提示用户使用 --prerelease=allow 重新运行，以允许所有依赖项的预发布版本。

Alternatively, you can add the transitive dependency to your requirements.in file with pre-release specifier (e.g., flask>=2.0.0rc1) to opt in to pre-release support for that specific dependency.
或者，您可以将传递性依赖项添加到您的 requirements.in 文件中，并使用预发布说明符（例如， flask>=2.0.0rc1 ）来选择支持该特定依赖项的预发布版本。

Pre-releases are notoriously difficult to model, and are a frequent source of bugs in other packaging tools. uv's pre-release handling is intentionally limited and intentionally requires user opt-in for pre-releases, to ensure correctness.
预发布版本极具挑战性，是其他打包工具中常见错误的来源。uv 的预发布处理有意受限，并故意要求用户选择接受预发布版本，以确保正确性。

For more, see "Pre-release compatibility"
有关更多信息，请参阅“预发布兼容性”

Historically, pip has supported "constraints" (-c constraints.txt), which allows users to narrow the set of acceptable versions for a given package.
从历史上看， pip 支持“约束” ( -c constraints.txt )，允许用户缩小给定软件包可接受版本的范围。

uv supports constraints, but also takes this concept further by allowing users to override the 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 declares pydantic>=1.0,<2.0, but the user knows that the package is compatible with pydantic>=2.0, the user can override the declared dependency with pydantic>=2.0,<3 to allow the resolver to continue.

While constraints are purely additive, and thus cannot expand the set of acceptable versions for a package, overrides can expand the set of acceptable versions for a package, providing an escape hatch for erroneous upper version bounds.

By default, uv's pip-compile command produces a resolution that's known to be compatible with the current platform and Python version. Unlike Poetry and PDM, uv does not yet produce a machine-agnostic lockfile (#2679).

However, uv does support resolving for alternate platforms and Python versions via the --python-platform and --python-version command line arguments.

For example, if you're running uv on macOS, but want to resolve for Linux, you can run uv pip compile --python-platform=linux requirements.in to produce a manylinux2014-compatible resolution.

Similarly, if you're running uv on Python 3.9, but want to resolve for Python 3.8, you can run uv pip compile --python-version=3.8 requirements.in to produce a Python 3.8-compatible resolution.

The --python-platform and --python-version arguments can be combined to produce a resolution for a specific platform and Python version, enabling users to generate multiple lockfiles for different environments from a single machine.

N.B. Python's environment markers expose far more information about the current machine than can be expressed by a simple --python-platform argument. For example, the platform_version marker on macOS includes the time at which the kernel was built, which can (in theory) be encoded in package requirements. uv's resolver makes a best-effort attempt to generate a resolution that is compatible with any machine running on the target --python-platform, which should be sufficient for most use cases, but may lose fidelity for complex package and platform combinations.

uv supports an --exclude-newer option to limit resolution to distributions published before a specific date, allowing reproduction of installations regardless of new package releases. The date may be specified as a RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or UTC date in the same format (e.g., 2006-12-02).

Note the package index must support the upload-time field as specified in PEP 700. If the field is not present for a given distribution, the distribution will be treated as unavailable.

To ensure reproducibility, messages for unsatisfiable resolutions will not mention that distributions were excluded due to the --exclude-newer flag — newer distributions will be treated as if they do not exist.

By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS, where reading the system trust store incurs a significant delay).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store. To instruct uv to use the system's trust store, run uv with the --native-tls command-line flag, or set the UV_NATIVE_TLS environment variable to true.

If a direct path to the certificate is required (e.g., in CI), set the SSL_CERT_FILE environment variable to the path of the certificate bundle, to instruct uv to use that file instead of the system's trust store.

uv 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 to PyPI for 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 known not to 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.

uv accepts the following command-line arguments as environment variables:

• UV_INDEX_URL: Equivalent to the --index-url command-line argument. If set, uv will use this URL as the base index for searching for packages.
• UV_EXTRA_INDEX_URL: Equivalent to the --extra-index-url command-line argument. If set, uv will use this space-separated list of URLs as additional indexes when searching for packages.
• UV_CACHE_DIR: Equivalent to the --cache-dir command-line argument. If set, uv will use this directory for caching instead of the default cache directory.
• UV_NO_CACHE: Equivalent to the --no-cache command-line argument. If set, uv will not use the cache for any operations.
• UV_RESOLUTION: Equivalent to the --resolution command-line argument. For example, if set to lowest-direct, uv will install the lowest compatible versions of all direct dependencies.
• UV_PRERELEASE: Equivalent to the --prerelease command-line argument. For example, if set to allow, uv will allow pre-release versions for all dependencies.
• UV_SYSTEM_PYTHON: Equivalent to the --system command-line argument. If set to true, uv will use the first Python interpreter found in the system PATH. WARNING: UV_SYSTEM_PYTHON=true is intended for use in continuous integration (CI) or containerized environments and should be used with caution, as modifying the system Python can lead to unexpected behavior.
• UV_PYTHON: Equivalent to the --python command-line argument. If set to a path, uv will use this Python interpreter for all operations.
• UV_BREAK_SYSTEM_PACKAGES: Equivalent to the --break-system-packages command-line argument. If set to true, uv will allow the installation of packages that conflict with system-installed packages. WARNING: UV_BREAK_SYSTEM_PACKAGES=true is intended for use in continuous integration (CI) or containerized environments and should be used with caution, as modifying the system Python can lead to unexpected behavior.
• UV_NATIVE_TLS: Equivalent to the --native-tls command-line argument. If set to true, uv will use the system's trust store instead of the bundled webpki-roots crate.
• UV_INDEX_STRATEGY: Equivalent to the --index-strategy command-line argument. For example, if set to unsafe-any-match, uv will consider versions of a given package available across all index URLs, rather than limiting its search to the first index URL that contains the package.
• UV_REQUIRE_HASHES: Equivalent to the --require-hashes command-line argument. If set to true, uv will require that all dependencies have a hash specified in the requirements file.
• UV_CONSTRAINT: Equivalent to the --constraint command-line argument. If set, uv will use this file as the constraints file. Uses space-separated list of files.
• UV_LINK_MODE: Equivalent to the --link-mode command-line argument. If set, uv will use this as a link mode.
• UV_NO_BUILD_ISOLATION: Equivalent to the --no-build-isolation command-line argument. If set, uv will skip isolation when building source distributions.

In each case, the corresponding command-line argument takes precedence over an environment variable.

In addition, uv respects the following environment variables:

• SSL_CERT_FILE: If set, uv will use this file as the certificate bundle instead of the system's trust store.
• RUST_LOG: If set, uv will use this value as the log level for its --verbose output. Accepts any filter compatible with the tracing_subscriber crate. For example, RUST_LOG=trace will enable trace-level logging. See the tracing documentation for more.
• HTTP_PROXY, HTTPS_PROXY, ALL_PROXY: The proxy to use for all HTTP/HTTPS requests.
• HTTP_TIMEOUT (or UV_HTTP_TIMEOUT): If set, uv will use this value (in seconds) as the timeout for HTTP reads (default: 30s).
• PYC_INVALIDATION_MODE: The validation modes to use when run with --compile. See: PycInvalidationMode.
• VIRTUAL_ENV: Used to detect an activated virtual environment.
• CONDA_PREFIX: Used to detect an activated Conda environment.
• PROMPT: Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).
• NU_VERSION: Used to detect the use of NuShell.
• FISH_VERSION: Used to detect the use of the Fish shell.
• BASH_VERSION: Used to detect the use of the Bash shell.
• ZSH_VERSION: Used to detect the use of the Zsh shell.
• RAYON_NUM_THREADS: Used to control the number of threads used when unzipping and installing packages. See the rayon documentation for more.

uv uses a custom versioning scheme in which the minor version number is bumped for breaking changes, and the patch version number is bumped for bug fixes, enhancements, and other non-breaking changes.

uv does not yet have a stable API; once uv's API is stable (v1.0.0), the versioning scheme will adhere to Semantic Versioning.

uv's dependency resolver uses PubGrub under the hood. We're grateful to the PubGrub maintainers, especially Jacob Finkelman, for their support.

uv's Git implementation is based on Cargo.

Some of uv's optimizations are inspired by the great work we've seen in pnpm, Orogene, and Bun. We've also learned a lot from Nathaniel J. Smith's Posy and adapted its trampoline for Windows support.

uv is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://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.