diff --git a/README.md b/README.md index 31ca68374ee0d..8aa256df81a81 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,7 @@ [![Actions status](https://github.com/astral-sh/uv/actions/workflows/ci.yml/badge.svg)](https://github.com/astral-sh/uv/actions) [![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white)](https://discord.gg/astral-sh) -An extremely fast Python package installer and resolver, written in Rust. Designed as a drop-in -replacement for common `pip` and `pip-tools` workflows. +An extremely fast Python package and project manager, written in Rust.

@@ -24,662 +23,238 @@ replacement for common `pip` and `pip-tools` workflows. ## Highlights -- โš–๏ธ Drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. -- โšก๏ธ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip` and - `pip-tools` (`pip-compile` and `pip-sync`). -- ๐Ÿ’พ 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. -- ๐Ÿงช Tested at-scale against the top 10,000 PyPI packages. -- ๐Ÿ–ฅ๏ธ Support for macOS, Linux, and Windows. -- ๐Ÿงฐ Advanced features such as [dependency version overrides](#dependency-overrides) and - [alternative resolution strategies](#resolution-strategy). -- โ‰๏ธ 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. +- ๐Ÿš€ A single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `virtualenv`, and more. +- โšก๏ธ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip`. +- ๐Ÿ [Installs and manages](#python-management) Python versions. +- ๐Ÿ› ๏ธ [Runs and installs](#tool-management) Python applications. +- โ‡๏ธ [Runs single-file scripts](#script-support), with support for + [inline dependency metadata](https://docs.astral.sh/uv/guides/scripts#declaring-script-dependencies). +- ๐Ÿ—‚๏ธ Provides [comprehensive project management](#project-management), with a + [universal lockfile](https://docs.astral.sh/uv/concepts/projects#lockfile). +- ๐Ÿ”ฉ Includes a [pip-compatible interface](#the-pip-interface) for a performance boost with a + familiar CLI. +- ๐Ÿข Supports Cargo-style [workspaces](https://docs.astral.sh/uv/concepts/workspaces) for scalable + projects. +- ๐Ÿ’พ Disk-space efficient, with a [global cache](https://docs.astral.sh/uv/concepts/cache) for + dependency deduplication. +- โฌ Installable without Rust or Python via `curl` or `pip`. +- ๐Ÿ–ฅ๏ธ Supports macOS, Linux, and Windows. uv is backed by [Astral](https://astral.sh), the creators of [Ruff](https://github.com/astral-sh/ruff). -## Getting Started +## Installation Install uv with our standalone installers, or from [PyPI](https://pypi.org/project/uv/): -```shell +```console # On macOS and Linux. -curl -LsSf https://astral.sh/uv/install.sh | sh +$ curl -LsSf https://astral.sh/uv/install.sh | sh # On Windows. -powershell -c "irm https://astral.sh/uv/install.ps1 | iex" - -# For a specific version. -curl -LsSf https://astral.sh/uv/0.2.37/install.sh | sh -powershell -c "irm https://astral.sh/uv/0.2.37/install.ps1 | iex" +$ 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 +$ pip install uv ``` -To create a virtual environment: +See the [installation documentation](https://docs.astral.sh/uv/getting-started/installation/) for +details and alternative installation methods. -```shell -uv venv # Create a virtual environment at `.venv`. -``` +## Documentation -To activate the virtual environment: +uv's documentation is available at [docs.astral.sh/uv](https://docs.astral.sh/uv). -```shell -# On macOS and Linux. -source .venv/bin/activate +Additionally, the command line reference documentation can be viewed with `uv help`. -# On Windows. -.venv\Scripts\activate -``` +## Features -To install a package into the virtual environment: +### Project management -```shell -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. -``` +uv manages project dependencies and environments, with support for lockfiles, workspaces, and more, +similar to `rye` or `poetry`: -To generate a set of locked dependencies: +```console +$ uv init example +Initialized project `example` at `/home/user/example` -```shell -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. -``` +$ cd example -To sync a set of locked dependencies with the virtual environment: +$ uv add ruff +Creating virtualenv at: .venv +Resolved 2 packages in 170ms + Built example @ file:///home/user/example +Prepared 2 packages in 627ms +Installed 2 packages in 1ms + + example==0.1.0 (from file:///home/user/example) + + ruff==0.5.4 -```shell -uv pip sync requirements.txt # Install from a requirements.txt file. +$ uv run ruff check +All checks passed! ``` -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. - -## Limitations - -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. - -For details, see our [`pip` compatibility guide](./PIP_COMPATIBILITY.md). - -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. - -## Roadmap - -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 represents an intermediary goal in our pursuit of a -["Cargo for Python"](https://blog.rust-lang.org/2016/05/05/cargo-pillars.html#pillars-of-cargo): 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 only `pip`, `pip-tools`, and `virtualenv`, but also `pipx`, -`tox`, `poetry`, `pyenv`, `ruff`, and more. - -Our goal is to evolve uv into such a tool. - -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. - -## Advanced Usage +See the [project documentation](https://docs.astral.sh/uv/guides/projects/) to get started. -### Python discovery +### Tool management -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 executes and installs command-line tools provided by Python packages, similar to `pipx`. -When running `pip sync` or `pip install`, uv will search for a virtual environment in the following -order: +Run a tool in an ephemeral environment with `uvx`: -- 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. +```console +$ uvx pycowsay 'hello world!' +Resolved 1 package in 167ms +Installed 1 package in 9ms + + pycowsay==0.0.0.2 + """ -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. - -### Installing into arbitrary Python environments - -Since uv has no dependency on Python, it can 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`, -regardless of where uv is installed. Note that if `VIRTUAL_ENV` is set to a directory that is -**not** a [PEP 405 compliant](https://peps.python.org/pep-0405/#specification) virtual environment, -it will be ignored. - -uv can also install into arbitrary, even non-virtual environments, with the `--python` argument -provided 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. Using -`--system` is roughly equivalent to `uv pip install --python=$(which python)`, but note that -executables that are linked to virtual environments will be skipped. Although we generally recommend -using virtual environments for dependency management, `--system` is appropriate in continuous -integration and containerized environments. - -The `--system` flag is also used to opt in to mutating system environments. For example, the -`--python` argument can be used to request a Python version (e.g., `--python 3.12`), and uv will -search for an interpreter that meets the request. If uv finds a system interpreter (e.g., -`/usr/lib/python3.12`), then the `--system` flag is required to allow modification of this -non-virtual Python environment. Without the `--system` flag, uv will ignore any interpreters that -are not in virtual environments. Conversely, when the `--system` flag is provided, uv will ignore -any interpreters that _are_ in virtual 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`)](https://ffy00.github.io/blog/02-python-debian-and-the-install-locations/). -While we always recommend the use of virtual environments, uv considers them to be required in these -non-standard environments. - -If uv is installed in a Python environment, e.g., with `pip`, it can still be used to modify other -environments. However, when invoked with `python -m uv`, uv will default to using the parent -interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for -general usage. - -### Persistent configuration - -uv supports persistent configuration at both the project- and user-level. - -Specifically, uv will search for a `pyproject.toml` or `uv.toml` file in the current directory, or -in the nearest parent directory. - -If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table. For -example, to set a persistent index URL, add the following to a `pyproject.toml`: - -```toml -[tool.uv.pip] -index-url = "https://test.pypi.org/simple" + ------------ +< hello world! > + ------------ + \ ^__^ + \ (oo)\_______ + (__)\ )\/\ + ||----w | + || || ``` -(If there is no such table, the `pyproject.toml` file will be ignored, and uv will continue -searching in the directory hierarchy.) +Install a tool with `uv tool install`: -If a `uv.toml` file is found, uv will read from the `[pip]` table. For example: +```console +$ uv tool install ruff +Resolved 1 package in 6ms +Installed 1 package in 2ms + + ruff==0.5.4 +Installed 1 executable: ruff -```toml -[pip] -index-url = "https://test.pypi.org/simple" +$ ruff --version +ruff 0.5.4 ``` -uv will also discover user-level configuration at `~/.config/uv/uv.toml` (or -`$XDG_CONFIG_HOME/uv/uv.toml`) on macOS and Linux, or `%APPDATA%\uv\uv.toml` on Windows. User-level -configuration must use the `uv.toml` format, rather than the `pyproject.toml` format, as a -`pyproject.toml` is intended to define a Python _project_. - -If both project- and user-level configuration are found, the settings will be merged, with the -project-level configuration taking precedence. Specifically, if a string, number, or boolean is -present in both tables, the project-level value will be used, and the user-level value will be -ignored. If an array is present in both tables, the arrays will be concatenated, with the -project-level settings appearing earlier in the merged array. - -Settings provided via environment variables take precedence over persistent configuration, and -settings provided via the command line take precedence over both. - -uv accepts a `--no-config` command-line argument which, when provided, disables the discovery of any -persistent configuration. - -uv also accepts a `--config-file` command-line argument, which accepts a path to a `uv.toml` to use -as the configuration file. When provided, this file will be used in place of _any_ discovered -configuration files (e.g., user-level configuration will be ignored). +See the [tools documentation](https://docs.astral.sh/uv/guides/tools/) to get started. -### Git authentication +### Python management -uv allows packages to be installed from Git and supports the following schemes for authenticating -with private repositories. +uv installs Python and allows quickly switching between versions. -Using SSH: +Install multiple Python versions: -- `git+ssh://git@/...` (e.g. `git+ssh://git@github.com/astral-sh/uv`) -- `git+ssh://git@/...` (e.g. `git+ssh://git@github.com-key-2/astral-sh/uv`) - -See the -[GitHub SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) -for more details on how to configure SSH. - -Using a password or token: - -- `git+https://:@/...` (e.g. - `git+https://git:github_pat_asdf@github.com/astral-sh/uv`) -- `git+https://@/...` (e.g. `git+https://github_pat_asdf@github.com/astral-sh/uv`) -- `git+https://@/...` (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, uv will query the -[Git credential helper](https://git-scm.com/doc/credential-helpers). - -### HTTP authentication - -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://:@/...` -- A [`netrc`](https://everything.curl.dev/usingcurl/netrc) configuration file -- A [keyring](https://github.com/jaraco/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](PIP_COMPATIBILITY.md#registry-authentication) for details on -differences from `pip`. - -### Dependency caching - -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`. - -### Resolution strategy - -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`). +```console +$ uv python install 3.10 3.11 3.12 +Searching for Python versions matching: Python 3.10 +Searching for Python versions matching: Python 3.11 +Searching for Python versions matching: Python 3.12 +Installed 3 versions in 3.42s + + cpython-3.10.14-macos-aarch64-none + + cpython-3.11.9-macos-aarch64-none + + cpython-3.12.4-macos-aarch64-none +``` -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. +Download Python versions as needed: -For example, given the following `requirements.in` file: +```console +$ uv venv --python 3.12.0 +Using Python 3.12.0 +Creating virtualenv at: .venv +Activate with: source .venv/bin/activate -```text -flask>=2.0.0 +$ uv run --python pypy@3.8 -- python --version +Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30) +[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin +Type "help", "copyright", "credits" or "license" for more information. +>>>> ``` -Running `uv pip compile requirements.in` would produce the following `requirements.txt` file: - -```text -# 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 -``` +Use a specific Python version in the current directory: -However, `uv pip compile --resolution=lowest requirements.in` would instead produce: - -```text -# 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 +``` +$ uv python pin pypy@3.11 +Pinned `.python-version` to `pypy@3.11` ``` -### Pre-release handling - -By default, uv will accept pre-release versions during dependency resolution in two cases: - -1. If the package is a direct dependency, and its version markers include a pre-release specifier - (e.g., `flask>=2.0.0rc1`). -1. 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. - -Alternatively, you can add the transitive dependency to your `requirements.in` file with a -pre-release specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific -dependency. - -Pre-releases are -[notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) 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. +See the [Python installation documentation](https://docs.astral.sh/uv/guides/install-python/) to get +started. -For more, see ["Pre-release compatibility"](./PIP_COMPATIBILITY.md#pre-release-compatibility) +### Script support -### Dependency overrides +uv manages dependencies and environments for single-file scripts. -Historically, `pip` has supported "constraints" (`-c constraints.txt`), which allows users to narrow -the set of acceptable versions for a given package. +Create a new script and add inline metadata declaring its dependencies: -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`). +```console +$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py -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. +$ uv add --script example.py requests +Updated `example.py` +``` -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. +Then, run the script in an isolated virtual environment: -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. +``` +$ uv run example.py +Reading inline script metadata from: example.py +Installed 5 packages in 12ms + +``` -### Platform-independent resolution +See the [scripts documentation](https://docs.astral.sh/uv/guides/scripts/) to get started. -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](https://github.com/astral-sh/uv/issues/2679)). +### A pip-compatible interface -However, uv _does_ support resolving for alternate platforms and Python versions via the -`--python-platform` and `--python-version` command line arguments. +uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. -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. +uv extends their interfaces with advanced features, such as dependency version overrides, +platform-independent resolutions, reproducible resolutions, alternative resolution strategies, and +more. -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. +Migrate to uv without changing your existing workflows โ€” and experience a 10-100x speedup โ€” with the +`uv pip` interface. -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. +Compile requirements into a platform-independent requirements file: -_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._ +```console +$ uv pip compile docs/requirements.in \ + --universal \ + --output-file docs/requirements.txt +Resolved 43 packages in 12ms +``` -### Time-restricted reproducible resolutions +Create a virtual environment: -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 an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamp (e.g., -`2006-12-02T02:07:43Z`) or a local date in the same format (e.g., `2006-12-02`) in your system's -configured time zone. +```console +$ uv venv +Using Python 3.12.3 +Creating virtualenv at: .venv +Activate with: source .venv/bin/activate +``` -Note the package index must support the `upload-time` field as specified in -[`PEP 700`](https://peps.python.org/pep-0700/). If the field is not present for a given -distribution, the distribution will be treated as unavailable. +Install the locked requirements: -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. +```console +$ uv pip sync docs/requirements.txt +Resolved 43 packages in 11ms +Installed 43 packages in 208ms + + babel==2.15.0 + + black==24.4.2 + + certifi==2024.7.4 + ... +``` -### Custom CA certificates +See the [pip interface documentation](https://docs.astral.sh/uv/pip/index/) to get started. -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). +## Platform support -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`. +See uv's [platform support](https://docs.astral.sh/uv/reference/platforms/) document. -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. +## Versioning policy -If client certificate authentication (mTLS) is desired, set the `SSL_CLIENT_CERT` environment -variable to the path of the PEM formatted file containing the certificate followed by the private -key. +See uv's [versioning policy](https://docs.astral.sh/uv/reference/versioning/) document. -## Platform support +## Contributing -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"](https://doc.rust-lang.org/beta/rustc/platform-support.html). - -uv has Tier 2 support -(["guaranteed to build"](https://doc.rust-lang.org/beta/rustc/platform-support.html)) for the -following platforms: - -- Linux (PPC64) -- Linux (PPC64LE) -- Linux (aarch64) -- Linux (armv7) -- Linux (i686) -- Linux (s390x) - -uv ships pre-built wheels to [PyPI](https://pypi.org/project/uv/) 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. The -minimum supported Windows version is Windows 10, following -[Rust's own Tier 1 support](https://blog.rust-lang.org/2024/02/26/Windows-7.html). - -uv supports and is tested against Python 3.8, 3.9, 3.10, 3.11, and 3.12. - -## Environment variables - -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_BUILD_CONSTRAINT`: Equivalent to the `--build-constraint` command-line argument. If set, uv - will use this file as constraints for any source distribution builds. Uses space-separated list of - files. -- `UV_OVERRIDE`: Equivalent to the `--override` command-line argument. If set, uv will use this file - as the overrides 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. -- `UV_CUSTOM_COMPILE_COMMAND`: Equivalent to the `--custom-compile-command` command-line argument. - Used to override uv in the output header of the `requirements.txt` files generated by - `uv pip compile`. Intended for use-cases in which `uv pip compile` is called from within a wrapper - script, to include the name of the wrapper script in the output file. -- `UV_KEYRING_PROVIDER`: Equivalent to the `--keyring-provider` command-line argument. If set, uv - will use this value as the keyring provider. -- `UV_CONFIG_FILE`: Equivalent to the `--config-file` command-line argument. Expects a path to a - local `uv.toml` file to use as the configuration file. -- `UV_NO_CONFIG`: Equivalent to the `--no-config` command-line argument. If set, uv will not read - any configuration files from the current directory, parent directories, or user configuration - directories. -- `UV_EXCLUDE_NEWER`: Equivalent to the `--exclude-newer` command-line argument. If set, uv will - exclude distributions published after the specified date. - -In each case, the corresponding command-line argument takes precedence over an environment variable. - -In addition, uv respects the following environment variables: - -- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that uv will - perform at any given time. -- `UV_CONCURRENT_BUILDS`: Sets the maximum number of source distributions that uv will build - concurrently at any given time. -- `UV_CONCURRENT_INSTALLS`: Used to control the number of threads used when installing and unzipping - packages. -- `UV_TOOL_DIR`: Used to specify the directory where uv will store managed tools. -- `UV_PYTHON_INSTALL_DIR`: Used to specify the directory where uv will store managed Python - installations. -- `UV_PYTHON_INSTALL_MIRROR`: Managed Python installations are downloaded from - [`python-build-standalone`](https://github.com/indygreg/python-build-standalone). This variable - can be set to a mirror URL to use a different source for Python installations. The provided URL - will replace `https://github.com/indygreg/python-build-standalone/releases/download` in, e.g., - `https://github.com/indygreg/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`. -- `UV_PYPY_INSTALL_MIRROR`: Managed PyPy installations are downloaded from - [python.org](https://downloads.python.org/). This variable can be set to a mirror URL to use a - different source for PyPy installations. The provided URL will replace - `https://downloads.python.org/pypy` in, e.g., - `https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`. -- `XDG_CONFIG_HOME`: Used to specify the path to uv user-level configuration directory on Linux - _and_ macOS systems. -- `XDG_CACHE_HOME`: Used to specify the directory where uv stores cache files on Linux system. -- `XDG_DATA_HOME`: Used to specify the directory where uv stores managed Python installations and - managed tools on Linux system. -- `XDG_BIN_HOME`: Used to specify the directory where executables are installed into. -- `SSL_CERT_FILE`: If set, uv will use this file as the certificate bundle instead of the system's - trust store. -- `SSL_CLIENT_CERT`: If set, uv will use this file for mTLS authentication. This should be a single - file containing both the certificate and the private key in PEM format. -- `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](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax) - 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: 30 s). -- `PYC_INVALIDATION_MODE`: The validation modes to use when run with `--compile`. See: - [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.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. -- `MACOSX_DEPLOYMENT_TARGET`: Used with `--python-platform macos` and related variants to set the - deployment target (i.e., the minimum supported macOS version). Defaults to `12.0`, the - least-recent non-EOL macOS version at time of writing. -- `NO_COLOR`: Disable colors. Takes precedence over `FORCE_COLOR`. See - [no-color.org](https://no-color.org). -- `FORCE_COLOR`: Enforce colors regardless of TTY support. See - [force-color.org](https://force-color.org). - -## Versioning - -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](https://semver.org/). +We are passionate about supporting contributors of all levels of experience and would love to see +you get involved in the project. See the +[contributing guide](https://github.com/astral-sh/uv/blob/main/CONTRIBUTING.md) to get started. ## Acknowledgements