diff --git a/.editorconfig b/.editorconfig index 05f81d3818218..59053366abbe2 100644 --- a/.editorconfig +++ b/.editorconfig @@ -18,3 +18,4 @@ trim_trailing_whitespace = false [*.md] max_line_length = 100 +indent_size = 4 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6d4621f28aa75..a592fcfe6f75e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -59,7 +59,7 @@ jobs: - name: "Prettier" run: | npx prettier --check "**/*.{json5,yaml,yml}" - npx prettier --prose-wrap always --check "**/*.md" + npx prettier --prose-wrap always --tab-width 4 --check "**/*.md" - name: "README check" run: python scripts/transform_readme.py --target pypi diff --git a/BENCHMARKS.md b/BENCHMARKS.md index c83a53d5fa957..49555f4151e2a 100644 --- a/BENCHMARKS.md +++ b/BENCHMARKS.md @@ -3,17 +3,18 @@ All benchmarks were computed on macOS using Python 3.12.0 (for non-uv tools), and come with a few important caveats: -- Benchmark performance may vary dramatically across different operating systems and filesystems. In - particular, uv uses different installation strategies based on the underlying filesystem's - capabilities. (For example, uv uses reflinking on macOS, and hardlinking on Linux.) -- Benchmark performance may vary dramatically depending on the set of packages being installed. For - example, a resolution that requires building a single intensive source distribution may appear - very similar across tools, since the bottleneck is tool-agnostic. -- Unlike Poetry, both uv and pip-tools do _not_ generate platform-independent lockfiles. As such, - Poetry is (by design) doing significantly more work than other tools in the resolution benchmarks. - Poetry is included for completeness, as many projects may not _need_ a platform-independent - lockfile. However, it's critical to understand that benchmarking uv's resolution time against - Poetry is an unfair comparison. (Benchmarking installation, however, _is_ a fair comparison.) +- Benchmark performance may vary dramatically across different operating systems and filesystems. + In particular, uv uses different installation strategies based on the underlying filesystem's + capabilities. (For example, uv uses reflinking on macOS, and hardlinking on Linux.) +- Benchmark performance may vary dramatically depending on the set of packages being installed. + For example, a resolution that requires building a single intensive source distribution may + appear very similar across tools, since the bottleneck is tool-agnostic. +- Unlike Poetry, both uv and pip-tools do _not_ generate platform-independent lockfiles. As such, + Poetry is (by design) doing significantly more work than other tools in the resolution + benchmarks. Poetry is included for completeness, as many projects may not _need_ a + platform-independent lockfile. However, it's critical to understand that benchmarking uv's + resolution time against Poetry is an unfair comparison. (Benchmarking installation, however, + _is_ a fair comparison.) This document benchmarks against Trio's `docs-requirements.in`, as a representative example of a real-world project. @@ -60,10 +61,10 @@ of other tools. The benchmark script itself has a several requirements: -- A local uv release build (`cargo build --release`). -- An installation of the production `uv` binary in your path. -- The [`hyperfine`](https://github.com/sharkdp/hyperfine) command-line tool installed on your - system. +- A local uv release build (`cargo build --release`). +- An installation of the production `uv` binary in your path. +- The [`hyperfine`](https://github.com/sharkdp/hyperfine) command-line tool installed on your + system. To benchmark resolution against pip-compile, Poetry, and PDM: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af26cb54304d8..b9fedb7eb656d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -141,13 +141,13 @@ To preview any changes to the documentation locally: 1. Run the development server with: - ```shell - # For contributors. - uvx --with-requirements docs/requirements.txt -- mkdocs serve -f mkdocs.public.yml + ```shell + # For contributors. + uvx --with-requirements docs/requirements.txt -- mkdocs serve -f mkdocs.public.yml - # For members of the Astral org, which has access to MkDocs Insiders via sponsorship. - uvx --with-requirements docs/requirements-insiders.txt -- mkdocs serve -f mkdocs.insiders.yml - ``` + # For members of the Astral org, which has access to MkDocs Insiders via sponsorship. + uvx --with-requirements docs/requirements-insiders.txt -- mkdocs serve -f mkdocs.insiders.yml + ``` The documentation should then be available locally at [http://127.0.0.1:8000/uv/](http://127.0.0.1:8000/uv/). @@ -167,7 +167,7 @@ Cloudflare Pages. After making changes to the documentation, format the markdown files with: ```shell -npx prettier --prose-wrap always --write "**/*.md" +npx prettier --prose-wrap always --tab-width 4 --write "**/*.md" ``` ## Releases diff --git a/PIP_COMPATIBILITY.md b/PIP_COMPATIBILITY.md index 8352d98867bab..bf04c3598a79f 100644 --- a/PIP_COMPATIBILITY.md +++ b/PIP_COMPATIBILITY.md @@ -97,11 +97,11 @@ the specifier, since it was provided as a direct dependency. As compared to pip, the main differences in observed behavior are as follows: -- In general, local versions must be provided as direct dependencies. Resolution may succeed for - transitive dependencies that request a non-local version, but this is not guaranteed. -- If _only_ local versions exist for a package `foo` at a given version (e.g., `1.2.3+local` exists, - but `1.2.3` does not), `uv pip install foo==1.2.3` will fail, while `pip install foo==1.2.3` will - resolve to an arbitrary local version. +- In general, local versions must be provided as direct dependencies. Resolution may succeed for + transitive dependencies that request a non-local version, but this is not guaranteed. +- If _only_ local versions exist for a package `foo` at a given version (e.g., `1.2.3+local` + exists, but `1.2.3` does not), `uv pip install foo==1.2.3` will fail, while + `pip install foo==1.2.3` will resolve to an arbitrary local version. ## Packages that exist on multiple indexes @@ -137,13 +137,13 @@ As of v0.1.39, users can opt in to `pip`-style behavior for multiple indexes via `--index-strategy` command-line option, or the `UV_INDEX_STRATEGY` environment variable, which supports the following values: -- `first-match` (default): Search for each package across all indexes, limiting the candidate - versions to those present in the first index that contains the package, prioritizing the - `--extra-index-url` indexes over the default index URL. -- `unsafe-first-match`: Search for each package across all indexes, but prefer the first index with - a compatible version, even if newer versions are available on other indexes. -- `unsafe-best-match`: Search for each package across all indexes, and select the best version from - the combined set of candidate versions. +- `first-match` (default): Search for each package across all indexes, limiting the candidate + versions to those present in the first index that contains the package, prioritizing the + `--extra-index-url` indexes over the default index URL. +- `unsafe-first-match`: Search for each package across all indexes, but prefer the first index + with a compatible version, even if newer versions are available on other indexes. +- `unsafe-best-match`: Search for each package across all indexes, and select the best version + from the combined set of candidate versions. While `unsafe-best-match` is the closest to `pip`'s behavior, it exposes users to the risk of "dependency confusion" attacks. @@ -298,12 +298,12 @@ too loose, and that the user should consider tightening them. For example, in th At present, `uv pip check` will surface the following diagnostics: -- A package has no `METADATA` file, or the `METADATA` file can't be parsed. -- A package has a `Requires-Python` that doesn't match the Python version of the running - interpreter. -- A package has a dependency on a package that isn't installed. -- A package has a dependency on a package that's installed, but at an incompatible version. -- Multiple versions of a package are installed in the virtual environment. +- A package has no `METADATA` file, or the `METADATA` file can't be parsed. +- A package has a `Requires-Python` that doesn't match the Python version of the running + interpreter. +- A package has a dependency on a package that isn't installed. +- A package has a dependency on a package that's installed, but at an incompatible version. +- Multiple versions of a package are installed in the virtual environment. In some cases, `uv pip check` will surface diagnostics that `pip check` does not, and vice versa. For example, unlike `uv pip check`, `pip check` will _not_ warn when multiple versions of a package @@ -364,8 +364,8 @@ does support a large subset. Missing options and subcommands are prioritized based on user demand and the complexity of the implementation, and tend to be tracked in individual issues. For example: -- [`--trusted-host`](https://github.com/astral-sh/uv/issues/1339) -- [`--user`](https://github.com/astral-sh/uv/issues/2077) +- [`--trusted-host`](https://github.com/astral-sh/uv/issues/1339) +- [`--user`](https://github.com/astral-sh/uv/issues/2077) If you encounter a missing option or subcommand, please search the issue tracker to see if it has already been reported, and if not, consider opening a new issue. Feel free to upvote any existing diff --git a/README.md b/README.md index 4e7302ea6224b..5e253cc7f4dd7 100644 --- a/README.md +++ b/README.md @@ -24,20 +24,20 @@ 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. +- โš–๏ธ 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. uv is backed by [Astral](https://astral.sh), the creators of [Ruff](https://github.com/astral-sh/ruff). @@ -154,9 +154,9 @@ dependencies into the environment and (2) build source distributions. 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. +- 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`. @@ -164,21 +164,21 @@ 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. +- 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. +- 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 @@ -272,8 +272,8 @@ with private repositories. Using SSH: -- `git+ssh://git@/...` (e.g. `git+ssh://git@github.com/astral-sh/uv`) -- `git+ssh://git@/...` (e.g. `git+ssh://git@github.zerozr99.workers.dev-key-2/astral-sh/uv`) +- `git+ssh://git@/...` (e.g. `git+ssh://git@github.com/astral-sh/uv`) +- `git+ssh://git@/...` (e.g. `git+ssh://git@github.zerozr99.workers.dev-key-2/astral-sh/uv`) See the [GitHub SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) @@ -281,10 +281,11 @@ 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`) +- `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 @@ -299,9 +300,9 @@ 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) +- 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 @@ -312,10 +313,10 @@ keyring-based authentication. Authentication may be used for hosts specified in the following contexts: -- `index-url` -- `extra-index-url` -- `find-links` -- `package @ https://...` +- `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`. @@ -327,15 +328,16 @@ 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. +- **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 @@ -348,11 +350,11 @@ 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`. +- 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 @@ -524,10 +526,10 @@ key. uv has Tier 1 support for the following platforms: -- macOS (Apple Silicon) -- macOS (x86_64) -- Linux (x86_64) -- Windows (x86_64) +- 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 @@ -537,12 +539,12 @@ 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) +- 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 @@ -559,98 +561,100 @@ 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_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`: 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_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_EXCLUDE_NEWER`: Equivalent to the `--exclude-newer` command-line argument. If set, uv will - exclude distributions published after the specified date. +- `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`: 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_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_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: -- `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). +- `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 @@ -678,9 +682,9 @@ for Windows support. uv is licensed under either of -- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or - https://www.apache.org/licenses/LICENSE-2.0) -- MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) +- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or + https://www.apache.org/licenses/LICENSE-2.0) +- MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) at your option. diff --git a/STYLE.md b/STYLE.md index 259f7071226cd..49ab97b77f401 100644 --- a/STYLE.md +++ b/STYLE.md @@ -102,18 +102,18 @@ The documentation is divided into: 1. `NO_COLOR` must be respected when using any colors or styling. 1. `UV_NO_PROGRESS` must be respected when using progress-styling like bars or spinners. 1. In general, use: - - Green for success. - - Red for error. - - Yellow for warning. - - Cyan for hints. - - Cyan for file paths. - - Cyan for important user-facing literals (e.g., a package name in a message). - - Green for commands. + - Green for success. + - Red for error. + - Yellow for warning. + - Cyan for hints. + - Cyan for file paths. + - Cyan for important user-facing literals (e.g., a package name in a message). + - Green for commands. ### Logging 1. `warn`, `info`, `debug`, and `trace` logs are all shown with the `--verbose` flag. - - Note that the displayed level is controlled with `RUST_LOG`. + - Note that the displayed level is controlled with `RUST_LOG`. 1. All logging should be to stderr. ### Output @@ -123,8 +123,8 @@ The documentation is divided into: ### Warnings 1. `warn_user` and `warn_user_once` are shown without the `--verbose `flag. - - These methods should be preferred over tracing warnings when the warning is actionable. - - Deprecation warnings should use these methods. + - These methods should be preferred over tracing warnings when the warning is actionable. + - Deprecation warnings should use these methods. 1. Deprecation warnings must be actionable. ### Hints diff --git a/crates/pep440-rs/Readme.md b/crates/pep440-rs/Readme.md index 477f923e09b77..d07e59a475a59 100644 --- a/crates/pep440-rs/Readme.md +++ b/crates/pep440-rs/Readme.md @@ -39,22 +39,22 @@ assert Version("2.0") in VersionSpecifier("==2") PEP 440 has a lot of unintuitive features, including: -- An epoch that you can prefix the version which, e.g. `1!1.2.3`. Lower epoch always means lower - version (`1.0 <=2!0.1`) - -* post versions, which can be attached to both stable releases and pre-releases -* dev versions, which can be attached to sbpth table releases and pre-releases. When attached to a - pre-release the dev version is ordered just below the normal pre-release, however when attached to - a stable version, the dev version is sorted before a pre-releases -* pre-release handling is a mess: "Pre-releases of any kind, including developmental releases, are - implicitly excluded from all version specifiers, unless they are already present on the system, - explicitly requested by the user, or if the only available version that satisfies the version - specifier is a pre-release.". This means that we can't say whether a specifier matches without - also looking at the environment -* pre-release vs. pre-release incl. dev is fuzzy -* local versions on top of all the others, which are added with a + and have implicitly typed string - and number segments -* no semver-caret (`^`), but a pseudo-semver tilde (`~=`) -* ordering contradicts matching: We have e.g. `1.0+local > 1.0` when sorting, but `==1.0` matches - `1.0+local`. While the ordering of versions itself is a total order the version matching needs to - catch all sorts of special cases +- An epoch that you can prefix the version which, e.g. `1!1.2.3`. Lower epoch always means lower + version (`1.0 <=2!0.1`) + +* post versions, which can be attached to both stable releases and pre-releases +* dev versions, which can be attached to sbpth table releases and pre-releases. When attached to a + pre-release the dev version is ordered just below the normal pre-release, however when attached + to a stable version, the dev version is sorted before a pre-releases +* pre-release handling is a mess: "Pre-releases of any kind, including developmental releases, are + implicitly excluded from all version specifiers, unless they are already present on the system, + explicitly requested by the user, or if the only available version that satisfies the version + specifier is a pre-release.". This means that we can't say whether a specifier matches without + also looking at the environment +* pre-release vs. pre-release incl. dev is fuzzy +* local versions on top of all the others, which are added with a + and have implicitly typed + string and number segments +* no semver-caret (`^`), but a pseudo-semver tilde (`~=`) +* ordering contradicts matching: We have e.g. `1.0+local > 1.0` when sorting, but `==1.0` matches + `1.0+local`. While the ordering of versions itself is a total order the version matching needs + to catch all sorts of special cases diff --git a/crates/pep440-rs/python/Readme.md b/crates/pep440-rs/python/Readme.md index 0cfdb536b0748..2c8e08615bffe 100644 --- a/crates/pep440-rs/python/Readme.md +++ b/crates/pep440-rs/python/Readme.md @@ -23,22 +23,22 @@ To only match final releases, filter with `.any_prelease()` beforehand. PEP 440 has a lot of unintuitive features, including: -- An epoch that you can prefix the version which, e.g. `1!1.2.3`. Lower epoch always means lower - version (`1.0 <=2!0.1`) - -* post versions, which can be attached to both stable releases and pre-releases -* dev versions, which can be attached to both table releases and pre-releases. When attached to a - pre-release the dev version is ordered just below the normal pre-release, however when attached to - a stable version, the dev version is sorted before a pre-releases -* pre-release handling is a mess: "Pre-releases of any kind, including developmental releases, are - implicitly excluded from all version specifiers, unless they are already present on the system, - explicitly requested by the user, or if the only available version that satisfies the version - specifier is a pre-release.". This means that we can't say whether a specifier matches without - also looking at the environment -* pre-release vs. pre-release incl. dev is fuzzy -* local versions on top of all the others, which are added with a + and have implicitly typed string - and number segments -* no semver-caret (`^`), but a pseudo-semver tilde (`~=`) -* ordering contradicts matching: We have e.g. `1.0+local > 1.0` when sorting, but `==1.0` matches - `1.0+local`. While the ordering of versions itself is a total order the version matching needs to - catch all sorts of special cases +- An epoch that you can prefix the version which, e.g. `1!1.2.3`. Lower epoch always means lower + version (`1.0 <=2!0.1`) + +* post versions, which can be attached to both stable releases and pre-releases +* dev versions, which can be attached to both table releases and pre-releases. When attached to a + pre-release the dev version is ordered just below the normal pre-release, however when attached + to a stable version, the dev version is sorted before a pre-releases +* pre-release handling is a mess: "Pre-releases of any kind, including developmental releases, are + implicitly excluded from all version specifiers, unless they are already present on the system, + explicitly requested by the user, or if the only available version that satisfies the version + specifier is a pre-release.". This means that we can't say whether a specifier matches without + also looking at the environment +* pre-release vs. pre-release incl. dev is fuzzy +* local versions on top of all the others, which are added with a + and have implicitly typed + string and number segments +* no semver-caret (`^`), but a pseudo-semver tilde (`~=`) +* ordering contradicts matching: We have e.g. `1.0+local > 1.0` when sorting, but `==1.0` matches + `1.0+local`. While the ordering of versions itself is a total order the version matching needs + to catch all sorts of special cases diff --git a/crates/uv-trampoline/README.md b/crates/uv-trampoline/README.md index 8ff40aa82a5d8..439328612b541 100644 --- a/crates/uv-trampoline/README.md +++ b/crates/uv-trampoline/README.md @@ -88,12 +88,12 @@ Basically, this looks up `python.exe` (for console programs) and invokes The intended use is: -- take your Python script, name it `__main__.py`, and pack it into a `.zip` file. Then concatenate - that `.zip` file onto the end of one of our prebuilt `.exe`s. -- After the zip file content, write the path to the Python executable that the script uses to run - the Python script as UTF-8 encoded string, followed by the path's length as a 32-bit little-endian - integer. -- At the very end, write the magic number `UVUV` in bytes. +- take your Python script, name it `__main__.py`, and pack it into a `.zip` file. Then concatenate + that `.zip` file onto the end of one of our prebuilt `.exe`s. +- After the zip file content, write the path to the Python executable that the script uses to run + the Python script as UTF-8 encoded string, followed by the path's length as a 32-bit + little-endian integer. +- At the very end, write the magic number `UVUV` in bytes. | `launcher.exe` | | :-------------------------: | @@ -126,24 +126,25 @@ In order to minimize binary size, this uses, `panic="abort"`, and carefully avoi Of course the tradeoff is that this is an awkward super-limited environment. No C runtime and limited platform APIs... you don't even panicking support by default. To work around this: -- We use `windows` to access Win32 APIs directly. Who needs a C runtime? Though uh, this does mean - that literally all of our code is `unsafe`. Sorry! +- We use `windows` to access Win32 APIs directly. Who needs a C runtime? Though uh, this does mean + that literally all of our code is `unsafe`. Sorry! -- `diagnostics.rs` uses `ufmt` and some cute Windows tricks to get a convenient version of - `eprintln!` that works without `core::fmt`, and automatically prints to either the console if - available or pops up a message box if not. +- `diagnostics.rs` uses `ufmt` and some cute Windows tricks to get a convenient version of + `eprintln!` that works without `core::fmt`, and automatically prints to either the console if + available or pops up a message box if not. -- All the meat is in `bounce.rs`. +- All the meat is in `bounce.rs`. Miscellaneous tips: -- `cargo-bloat` is a useful tool for checking what code is ending up in the final binary and how - much space it's taking. (It makes it very obvious whether you've pulled in `core::fmt`!) +- `cargo-bloat` is a useful tool for checking what code is ending up in the final binary and how + much space it's taking. (It makes it very obvious whether you've pulled in `core::fmt`!) -- Lots of Rust built-in panicking checks will pull in `core::fmt`, e.g., if you ever use `.unwrap()` - then suddenly our binaries double in size, because the `if foo.is_none() { panic!(...) }` that's - hidden inside `.unwrap()` will invoke `core::fmt`, even if the unwrap will actually never fail. - `.unwrap_unchecked()` avoids this. Similar for `slice[idx]` vs `slice.get_unchecked(idx)`. +- Lots of Rust built-in panicking checks will pull in `core::fmt`, e.g., if you ever use + `.unwrap()` then suddenly our binaries double in size, because the + `if foo.is_none() { panic!(...) }` that's hidden inside `.unwrap()` will invoke `core::fmt`, + even if the unwrap will actually never fail. `.unwrap_unchecked()` avoids this. Similar for + `slice[idx]` vs `slice.get_unchecked(idx)`. ### How do you build this stupid thing? diff --git a/docs/concepts/cache.md b/docs/concepts/cache.md index edf5b1326635e..4acd956b49e3a 100644 --- a/docs/concepts/cache.md +++ b/docs/concepts/cache.md @@ -7,15 +7,16 @@ 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. +- **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 @@ -27,21 +28,21 @@ are running, and _never_ safe to modify the cache directly (e.g., by removing a 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 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 ...`. ## Clearing the cache uv provides a few different mechanisms for removing entries from the cache: -- `uv cache clean` removes _all_ cache entries from the cache directory, clearing it out entirely. -- `uv cache clean ruff` removes all cache entries for the `ruff` package, useful for invalidating - the cache for a single or finite set of packages. -- `uv cache prune` removes all _unused_ cache entries. For example, the cache directory may contain - entries created in previous uv versions that are no longer necessary and can be safely removed. - `uv cache prune` is safe to run periodically, to keep the cache directory clean. +- `uv cache clean` removes _all_ cache entries from the cache directory, clearing it out entirely. +- `uv cache clean ruff` removes all cache entries for the `ruff` package, useful for invalidating + the cache for a single or finite set of packages. +- `uv cache prune` removes all _unused_ cache entries. For example, the cache directory may + contain entries created in previous uv versions that are no longer necessary and can be safely + removed. `uv cache prune` is safe to run periodically, to keep the cache directory clean. ## Caching in continuous integration diff --git a/docs/concepts/dependencies.md b/docs/concepts/dependencies.md index dd5c3ad8f9ba9..59b561b0afdb4 100644 --- a/docs/concepts/dependencies.md +++ b/docs/concepts/dependencies.md @@ -65,10 +65,10 @@ stands-compliant `project.dependencies` table. During development, a project may rely on a package that isn't available on PyPI. The following additional sources are supported by uv: -- Git: A Git repository. -- URL: A remote wheel or source distribution. -- Path: A local wheel, source distribution, or project directory. -- Workspace: A member of the current workspace. +- Git: A Git repository. +- URL: A remote wheel or source distribution. +- Path: A local wheel, source distribution, or project directory. +- Workspace: A member of the current workspace. Only a single source may be defined for each dependency. @@ -282,10 +282,10 @@ $ uv add ruff --dev [PEP 508](https://peps.python.org/pep-0508/) defines a syntax for dependency specification. It is composed of, in order: -- The dependency name -- The extras you want (optional) -- The version specifier -- An environment marker (optional) +- The dependency name +- The extras you want (optional) +- The version specifier +- An environment marker (optional) The version specifiers are comma separated and added together, e.g., `foo >=1.2.3,<2,!=1.4.0` is interpreted as "a version of `foo` that's at least 1.2.3, but less than 2, and not 1.4.0". diff --git a/docs/concepts/index.md b/docs/concepts/index.md index 5e3a02a745c60..1cc538e80f0da 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -2,12 +2,12 @@ Read the concept documents to learn more about uv's features: -- [Projects](./projects.md) -- [Dependencies](./dependencies.md) -- [Workspaces](./workspaces.md) -- [Tools](./tools.md) -- [Python versions](./python-versions.md) -- [Resolution](./resolution.md) -- [Caching](./cache.md) +- [Projects](./projects.md) +- [Dependencies](./dependencies.md) +- [Workspaces](./workspaces.md) +- [Tools](./tools.md) +- [Python versions](./python-versions.md) +- [Resolution](./resolution.md) +- [Caching](./cache.md) Looking for a quick introduction to features? See the [guides](../guides/index.md) instead. diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md index a2dc21ed4fd76..c487d0a4cfb3f 100644 --- a/docs/concepts/python-versions.md +++ b/docs/concepts/python-versions.md @@ -31,19 +31,19 @@ create the virtual environment with it. The following Python version request formats are supported: -- `` e.g. `3`, `3.12`, `3.12.3` -- `` e.g. `>=3.12,<3.13` -- `` e.g. `cpython` or `cp` -- `@` e.g. `cpython@3.12` -- `` e.g. `cpython3.12` or `cp312` -- `` e.g. `cpython>=3.12,<3.13` -- `----` e.g. `cpython-3.12.3-macos-aarch64-none` +- `` e.g. `3`, `3.12`, `3.12.3` +- `` e.g. `>=3.12,<3.13` +- `` e.g. `cpython` or `cp` +- `@` e.g. `cpython@3.12` +- `` e.g. `cpython3.12` or `cp312` +- `` e.g. `cpython>=3.12,<3.13` +- `----` e.g. `cpython-3.12.3-macos-aarch64-none` Additionally, a specific system Python interpreter can be requested with: -- `` e.g. `/opt/homebrew/bin/python3` -- `` e.g. `mypython3` -- `` e.g. `/some/environment/` +- `` e.g. `/opt/homebrew/bin/python3` +- `` e.g. `mypython3` +- `` e.g. `/some/environment/` By default, uv will automatically download Python versions if they cannot be found on the system. This behavior can be @@ -138,11 +138,11 @@ $ uv python list --only-installed When searching for a Python version, the following locations are checked: -- Managed Python installations in the `UV_PYTHON_INSTALL_DIR`. -- A Python interpreter on the `PATH` as `python`, `python3`, or `python3.x` on macOS and Linux, or - `python.exe` on Windows. -- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested - version. +- Managed Python installations in the `UV_PYTHON_INSTALL_DIR`. +- A Python interpreter on the `PATH` as `python`, `python3`, or `python3.x` on macOS and Linux, or + `python.exe` on Windows. +- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested + version. When performing discovery, non-executable files will be ignored. Each discovered executable is queried for metadata to ensure it meets the [requested Python version](#requesting-a-version). If @@ -169,9 +169,9 @@ system Python installations are still preferred over downloading a managed Pytho The following alternative options are available: -- `only-managed`: Only use managed Python installations; never use system Python installations -- `system`: Prefer system Python installations over managed Python installations -- `only-system`: Only use system Python installations; never use managed Python installations +- `only-managed`: Only use managed Python installations; never use system Python installations +- `system`: Prefer system Python installations over managed Python installations +- `only-system`: Only use system Python installations; never use managed Python installations These options allow disabling uv's managed Python versions entirely or always using them and ignoring any existing system installations. @@ -188,9 +188,9 @@ supported, uv will fail to discover its interpreter. The implementations may be requested with either the long or short name: -- CPython: `cpython`, `cp` -- PyPy: `pypy`, `pp` -- GraalPy: `graalpy`, `gp` +- CPython: `cpython`, `cp` +- PyPy: `pypy`, `pp` +- GraalPy: `graalpy`, `gp` Implementation name requests are not case sensitive. diff --git a/docs/concepts/resolution.md b/docs/concepts/resolution.md index 08c0e4b70626e..d5a3a04db29af 100644 --- a/docs/concepts/resolution.md +++ b/docs/concepts/resolution.md @@ -7,12 +7,12 @@ package versions that fulfil your requirements and the requirements of all inclu Imagine you have the following dependency tree: -- Your project depends on `foo>=1,<3` and `bar>=1,<3`. -- `foo` has two versions, 1.0.0 and 2.0.0. `foo` 2.0.0 depends on `lib==2.0.0`, `foo` 1.0.0 has no - dependencies. -- `bar` has two versions, 1.0.0 and 2.0.0. `bar` 2.0.0 depends on `lib==1.0.0`, `bar` 1.0.0 has no - dependencies. -- `lib` has two versions, 1.0.0 and 2.0.0. Both versions have no dependencies. +- Your project depends on `foo>=1,<3` and `bar>=1,<3`. +- `foo` has two versions, 1.0.0 and 2.0.0. `foo` 2.0.0 depends on `lib==2.0.0`, `foo` 1.0.0 has no + dependencies. +- `bar` has two versions, 1.0.0 and 2.0.0. `bar` 2.0.0 depends on `lib==1.0.0`, `bar` 1.0.0 has no + dependencies. +- `lib` has two versions, 1.0.0 and 2.0.0. Both versions have no dependencies. We can't install both `foo` 2.0.0 and `bar` 2.0.0 because they conflict on the version of `lib`, so the resolver will pick either `foo` 1.0.0 or `bar` 1.0.0. Both are valid solutions, at the resolvers diff --git a/docs/concepts/tools.md b/docs/concepts/tools.md index bb57f13c6a4dc..b827bbe515d94 100644 --- a/docs/concepts/tools.md +++ b/docs/concepts/tools.md @@ -102,9 +102,9 @@ notably including Windows and macOS โ€” there is no clear alternative location t these platforms. The installation directory is determined from the first available environment variable: -- `$XDG_BIN_HOME` -- `$XDG_DATA_HOME/../bin` -- `$HOME/.local/bin` +- `$XDG_BIN_HOME` +- `$XDG_DATA_HOME/../bin` +- `$HOME/.local/bin` Executables provided by dependencies of tool packages are not installed. @@ -130,8 +130,8 @@ $ uv run --no-project --with -- However, there are a couple notable differences when using uv's tool interface: -- The `--with` option is not needed โ€” the required package is inferred from the command name. -- The temporary environment is cached in a dedicated location. -- The `--no-project` flag is not needed โ€” tools are always run isolated from the project. -- If a tool is already installed, `uv tool run` will use the installed version but `uv run` will - not. +- The `--with` option is not needed โ€” the required package is inferred from the command name. +- The temporary environment is cached in a dedicated location. +- The `--no-project` flag is not needed โ€” tools are always run isolated from the project. +- If a tool is already installed, `uv tool run` will use the installed version but `uv run` will + not. diff --git a/docs/configuration/authentication.md b/docs/configuration/authentication.md index 637c2568c6c96..37175052d0ccd 100644 --- a/docs/configuration/authentication.md +++ b/docs/configuration/authentication.md @@ -7,8 +7,8 @@ with private repositories. Using SSH: -- `git+ssh://git@/...` (e.g. `git+ssh://git@github.com/astral-sh/uv`) -- `git+ssh://git@/...` (e.g. `git+ssh://git@github.zerozr99.workers.dev-key-2/astral-sh/uv`) +- `git+ssh://git@/...` (e.g. `git+ssh://git@github.com/astral-sh/uv`) +- `git+ssh://git@/...` (e.g. `git+ssh://git@github.zerozr99.workers.dev-key-2/astral-sh/uv`) See the [GitHub SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) @@ -16,10 +16,11 @@ 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`) +- `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 @@ -34,9 +35,9 @@ 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) +- 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 @@ -47,10 +48,10 @@ keyring-based authentication. Authentication may be used for hosts specified in the following contexts: -- `index-url` -- `extra-index-url` -- `find-links` -- `package @ https://...` +- `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`. diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md index b015314946931..7fb03f3fb0b1e 100644 --- a/docs/configuration/environment.md +++ b/docs/configuration/environment.md @@ -2,87 +2,88 @@ 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. -- `UV_CUSTOM_COMPILE_COMMAND`: 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_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_EXCLUDE_NEWER`: Equivalent to the `--exclude-newer` command-line argument. If set, uv will - exclude distributions published after the specified date. +- `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. +- `UV_CUSTOM_COMPILE_COMMAND`: 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_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_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: -- `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). +- `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). diff --git a/docs/configuration/index.md b/docs/configuration/index.md index 8f0bc1f3edced..6070266d20f98 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -2,9 +2,9 @@ Read about the various ways to configure uv: -- [Using configuration files](./files.md) -- [Using environment variables](./environment.md) -- [Configuring authentication](./authentication.md) +- [Using configuration files](./files.md) +- [Using environment variables](./environment.md) +- [Configuring authentication](./authentication.md) Or, jump to the [settings reference](../reference/settings.md) which enumerates the available configuration options. diff --git a/docs/features.md b/docs/features.md index 586d9031e68d9..8cd5748429ff1 100644 --- a/docs/features.md +++ b/docs/features.md @@ -9,11 +9,11 @@ uv's interface can be broken down into sections, which can be used independently Installing and managing Python itself. -- `uv python install`: Install Python versions. -- `uv python list`: View available Python versions. -- `uv python find`: Find an installed Python version. -- `uv python pin`: Pin the current project to use a specific Python version. -- `uv python uninstall`: Uninstall a Python version. +- `uv python install`: Install Python versions. +- `uv python list`: View available Python versions. +- `uv python find`: Find an installed Python version. +- `uv python pin`: Pin the current project to use a specific Python version. +- `uv python uninstall`: Uninstall a Python version. See the [guide on installing Python](./guides/install-python.md) to get started. @@ -21,7 +21,7 @@ See the [guide on installing Python](./guides/install-python.md) to get started. Executing standalone Python scripts, e.g., `example.py`. -- `uv run`: Run a script. +- `uv run`: Run a script. See the [guide on running scripts](./guides/scripts.md) to get started. @@ -29,13 +29,13 @@ See the [guide on running scripts](./guides/scripts.md) to get started. Creating and working on Python projects, i.e., with a `pyproject.toml`. -- `uv init`: Create a new Python project. -- `uv add`: Add a dependency to the project. -- `uv remove`: Remove a dependency from the project. -- `uv sync`: Sync the project's dependencies with the environment. -- `uv lock`: Create a lockfile for the project's dependencies. -- `uv run`: Run a command in the project environment. -- `uv tree`: View the dependency tree for the project. +- `uv init`: Create a new Python project. +- `uv add`: Add a dependency to the project. +- `uv remove`: Remove a dependency from the project. +- `uv sync`: Sync the project's dependencies with the environment. +- `uv lock`: Create a lockfile for the project's dependencies. +- `uv run`: Run a command in the project environment. +- `uv tree`: View the dependency tree for the project. See the [guide on projects](./guides/projects.md) to get started. @@ -43,11 +43,11 @@ See the [guide on projects](./guides/projects.md) to get started. Running and installing tools published to Python package indexes, e.g., `ruff` or `black`. -- `uvx` / `uv tool run`: Run a tool in a temporary environment. -- `uv tool install`: Install a tool user-wide. -- `uv tool uninstall`: Uninstall a tool. -- `uv tool list`: List installed tools. -- `uv tool update-shell`: Update the shell to include tool executables. +- `uvx` / `uv tool run`: Run a tool in a temporary environment. +- `uv tool install`: Install a tool user-wide. +- `uv tool uninstall`: Uninstall a tool. +- `uv tool list`: List installed tools. +- `uv tool update-shell`: Update the shell to include tool executables. See the [guide on tools](./guides/tools.md) to get started. @@ -58,27 +58,27 @@ the high-level commands do not provide enough control. Creating virtual environments (replacing `venv` and `virtualenv`): -- `uv venv`: Create a new virtual environment. +- `uv venv`: Create a new virtual environment. See the documentation on [using environments](./pip/environments.md) for details. Managing packages in an environment (replacing [`pip`](https://github.com/pypa/pip) and [`pipdeptree`](https://github.com/tox-dev/pipdeptree)): -- `uv pip install`: Install packages into the current environment. -- `uv pip show`: Show details about an installed package. -- `uv pip freeze`: List installed packages and their versions. -- `uv pip check`: Check that the current environment has compatible packages. -- `uv pip list`: List installed packages. -- `uv pip uninstall`: Uninstall packages. -- `uv pip tree`: View the dependency tree for the environment. +- `uv pip install`: Install packages into the current environment. +- `uv pip show`: Show details about an installed package. +- `uv pip freeze`: List installed packages and their versions. +- `uv pip check`: Check that the current environment has compatible packages. +- `uv pip list`: List installed packages. +- `uv pip uninstall`: Uninstall packages. +- `uv pip tree`: View the dependency tree for the environment. See the documentation on [managing packages](./pip/packages.md) for details. Locking packages in an environment (replacing [`pip-tools`](https://github.com/jazzband/pip-tools)): -- `uv pip compile`: Compile requirements into a lockfile. -- `uv pip sync`: Sync an environment with a lockfile. +- `uv pip compile`: Compile requirements into a lockfile. +- `uv pip sync`: Sync an environment with a lockfile. See the documentation on [locking environments](./pip/compile.md) for details. @@ -91,9 +91,9 @@ See the documentation on [locking environments](./pip/compile.md) for details. Managing and inspecting uv's state, such as the cache, storage directories, or performing a self-update: -- `uv cache clean`: Remove cache entries. -- `uv cache prune`: Remove outdated cache entries. -- `uv cache dir`: Show the uv cache directory path. -- `uv tool dir`: Show the uv tool directory path. -- `uv python dir`: Show the uv installed Python versions path. -- `uv self update`: Update uv to the latest version. +- `uv cache clean`: Remove cache entries. +- `uv cache prune`: Remove outdated cache entries. +- `uv cache dir`: Show the uv cache directory path. +- `uv tool dir`: Show the uv tool directory path. +- `uv python dir`: Show the uv installed Python versions path. +- `uv self update`: Update uv to the latest version. diff --git a/docs/guides/index.md b/docs/guides/index.md index 4f5ff70ae9cae..5beb080359b62 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -2,17 +2,17 @@ Check out one of the core guides to get started: -- [Installing Python versions](./install-python.md) -- [Running scripts and declaring dependencies](./scripts.md) -- [Running and installing applications as tools](./tools.md) -- [Creating and working on projects](./projects.md) +- [Installing Python versions](./install-python.md) +- [Running scripts and declaring dependencies](./scripts.md) +- [Running and installing applications as tools](./tools.md) +- [Creating and working on projects](./projects.md) Learn how to integrate uv with other software: -- [Using in Docker images](./integration/docker.md) -- [Using with pre-commit](./integration/pre-commit.md) -- [Using in GitHub Actions](./integration/github.md) -- [Using with alternative package indexes](./integration/alternative-indexes.md) +- [Using in Docker images](./integration/docker.md) +- [Using with pre-commit](./integration/pre-commit.md) +- [Using in GitHub Actions](./integration/github.md) +- [Using with alternative package indexes](./integration/alternative-indexes.md) Or, explore the [concept documentation](../concepts/index.md) for comprehensive breakdown of each feature. diff --git a/docs/guides/integration/github.md b/docs/guides/integration/github.md index 0bf3e15cc3f55..a64de15b8f018 100644 --- a/docs/guides/integration/github.md +++ b/docs/guides/integration/github.md @@ -10,16 +10,16 @@ uv installation differs depending on the platform. name: Example on Unix jobs: - uv-example-linux: - name: python-linux - runs-on: ubuntu-latest + uv-example-linux: + name: python-linux + runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 + steps: + - uses: actions/checkout@v4 - - name: Set up uv - # Install uv using the standalone installer - run: curl -LsSf https://astral.sh/uv/install.sh | sh + - name: Set up uv + # Install uv using the standalone installer + run: curl -LsSf https://astral.sh/uv/install.sh | sh ``` ### Windows @@ -28,17 +28,17 @@ jobs: name: Example on Windows jobs: - uv-example-windows: - name: python-windows - runs-on: windows-latest + uv-example-windows: + name: python-windows + runs-on: windows-latest - steps: - - uses: actions/checkout@v4 + steps: + - uses: actions/checkout@v4 - - name: Set up uv - # Install uv using the standalone installer - run: irm https://astral.sh/uv/install.ps1 | iex - shell: powershell + - name: Set up uv + # Install uv using the standalone installer + run: irm https://astral.sh/uv/install.ps1 | iex + shell: powershell ``` ### Using a matrix @@ -47,31 +47,31 @@ jobs: name: Example jobs: - uv-example-multiplatform: - name: python-${{ matrix.os }} + uv-example-multiplatform: + name: python-${{ matrix.os }} - strategy: - matrix: - os: - - ubuntu-latest - - windows-latest - - macos-latest + strategy: + matrix: + os: + - ubuntu-latest + - windows-latest + - macos-latest - fail-fast: false + fail-fast: false - runs-on: ${{ matrix.os }} + runs-on: ${{ matrix.os }} - steps: - - uses: actions/checkout@v4 + steps: + - uses: actions/checkout@v4 - - name: Set up uv - if: ${{ matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest' }} - run: curl -LsSf https://astral.sh/uv/install.sh | sh + - name: Set up uv + if: ${{ matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest' }} + run: curl -LsSf https://astral.sh/uv/install.sh | sh - - name: Set up uv - if: ${{ matrix.os == 'windows-latest' }} - run: irm https://astral.sh/uv/install.ps1 | iex - shell: powershell + - name: Set up uv + if: ${{ matrix.os == 'windows-latest' }} + run: irm https://astral.sh/uv/install.ps1 | iex + shell: powershell ``` ## Setting up Python @@ -80,10 +80,10 @@ Python can be installed with the `python install` command: ```yaml title="example.yml" steps: - # ... setup up uv ... + # ... setup up uv ... - - name: Set up Python - run: uv python install + - name: Set up Python + run: uv python install ``` This will respect the Python version pinned in the project. @@ -92,21 +92,21 @@ Or, when using a matrix, as in: ```yaml title="example.yml" strategy: - matrix: - python-version: - - "3.10" - - "3.11" - - "3.12" + matrix: + python-version: + - "3.10" + - "3.11" + - "3.12" ``` Provide the version to the `python install` invocation: ```yaml title="example.yml" steps: - # ... setup up uv ... + # ... setup up uv ... - - name: Set up Python ${{ matrix.python-version }} - run: uv python install ${{ matrix.python-version }} + - name: Set up Python ${{ matrix.python-version }} + run: uv python install ${{ matrix.python-version }} ``` Alternatively, the official GitHub `setup-python` action can be used. This is generally faster, but @@ -114,10 +114,10 @@ will not respect the project's pinned Python version. ```yaml title="example.yml" steps: - - name: "Set up Python" - uses: actions/setup-python@v5 - with: - python-version: 3.12 + - name: "Set up Python" + uses: actions/setup-python@v5 + with: + python-version: 3.12 ``` ## Syncing and running @@ -127,14 +127,14 @@ run in the environment with `uv run`: ```yaml title="example.yml" steps: - # ... setup up Python and uv ... + # ... setup up Python and uv ... - - name: Install the project - run: uv sync --all-extras --dev + - name: Install the project + run: uv sync --all-extras --dev - - name: Run tests - # For example, using `pytest` - run: uv run pytest tests + - name: Run tests + # For example, using `pytest` + run: uv run pytest tests ``` ## Caching @@ -145,27 +145,27 @@ The cache can be saved and restored with the official GitHub `cache` action: ```yaml title="example.yml" jobs: - install_job: - env: - # Configure a constant location for the uv cache - UV_CACHE_DIR: /tmp/.uv-cache - - steps: - # ... setup up Python and uv ... - - - name: Restore uv cache - uses: actions/cache@v4 - with: - path: /tmp/.uv-cache - key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }} - restore-keys: | - uv-${{ runner.os }}-${{ hashFiles('uv.lock') }} - uv-${{ runner.os }} - - # ... install packages, run tests, etc ... - - - name: Minimize uv cache - run: uv cache prune --ci + install_job: + env: + # Configure a constant location for the uv cache + UV_CACHE_DIR: /tmp/.uv-cache + + steps: + # ... setup up Python and uv ... + + - name: Restore uv cache + uses: actions/cache@v4 + with: + path: /tmp/.uv-cache + key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }} + restore-keys: | + uv-${{ runner.os }}-${{ hashFiles('uv.lock') }} + uv-${{ runner.os }} + + # ... install packages, run tests, etc ... + + - name: Minimize uv cache + run: uv cache prune --ci ``` The `uv cache prune --ci` command is used to reduce the size of the cache and is optimized for CI. @@ -187,7 +187,7 @@ Opt-in for the entire workflow by defining it at the top level: ```yaml title="example.yml" env: - UV_SYSTEM_PYTHON: 1 + UV_SYSTEM_PYTHON: 1 jobs: ... ``` @@ -206,10 +206,10 @@ Or, opt-in for a specific step in a job: ```yaml title="example.yml" steps: - - name: Install requirements - run: uv pip install -r requirements.txt - env: - UV_SYSTEM_PYTHON: 1 + - name: Install requirements + run: uv pip install -r requirements.txt + env: + UV_SYSTEM_PYTHON: 1 ``` To opt-out again, the `--no-system` flag can be used in any uv invocation. diff --git a/docs/guides/integration/index.md b/docs/guides/integration/index.md index 01a20e77d0256..b019f9ac181a4 100644 --- a/docs/guides/integration/index.md +++ b/docs/guides/integration/index.md @@ -2,7 +2,7 @@ Learn how to integrate uv with other software: -- [Using in Docker images](./docker.md) -- [Using with pre-commit](./pre-commit.md) -- [Using in GitHub Actions](./github.md) -- [Using an Azure Artifacts index](./alternative-indexes.md#azure-artifacts) +- [Using in Docker images](./docker.md) +- [Using with pre-commit](./pre-commit.md) +- [Using in GitHub Actions](./github.md) +- [Using an Azure Artifacts index](./alternative-indexes.md#azure-artifacts) diff --git a/docs/guides/integration/pre-commit.md b/docs/guides/integration/pre-commit.md index b24b0b9d6f058..1a72d0b0f4381 100644 --- a/docs/guides/integration/pre-commit.md +++ b/docs/guides/integration/pre-commit.md @@ -10,9 +10,9 @@ To compile requirements via pre-commit, add the following to the `.pre-commit-co # uv version. rev: 0.2.33 hooks: - # Compile requirements - - id: pip-compile - args: [requirements.in, -o, requirements.txt] + # Compile requirements + - id: pip-compile + args: [requirements.in, -o, requirements.txt] ``` To compile alternative files, modify `args` and `files`: @@ -22,10 +22,10 @@ To compile alternative files, modify `args` and `files`: # uv version. rev: 0.2.33 hooks: - # Compile requirements - - id: pip-compile - args: [requirements-dev.in, -o, requirements-dev.txt] - files: ^requirements-dev\.(in|txt)$ + # Compile requirements + - id: pip-compile + args: [requirements-dev.in, -o, requirements-dev.txt] + files: ^requirements-dev\.(in|txt)$ ``` To run the hook over multiple files at the same time: @@ -35,12 +35,12 @@ To run the hook over multiple files at the same time: # uv version. rev: 0.2.33 hooks: - # Compile requirements - - id: pip-compile - name: pip-compile requirements.in - args: [requirements.in, -o, requirements.txt] - - id: pip-compile - name: pip-compile requirements-dev.in - args: [requirements-dev.in, -o, requirements-dev.txt] - files: ^requirements-dev\.(in|txt)$ + # Compile requirements + - id: pip-compile + name: pip-compile requirements.in + args: [requirements.in, -o, requirements.txt] + - id: pip-compile + name: pip-compile requirements-dev.in + args: [requirements-dev.in, -o, requirements-dev.txt] + files: ^requirements-dev\.(in|txt)$ ``` diff --git a/docs/index.md b/docs/index.md index 7fe43d3c9ec9c..59ca0ad9332be 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,18 +16,20 @@ An extremely fast Python package and project manager, written in Rust. ## Highlights -- ๐Ÿš€ 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](./guides/install-python.md) Python versions. -- ๐Ÿ› ๏ธ [Runs and installs](./guides/tools.md) Python applications. -- โ‡๏ธ [Runs scripts](./guides/scripts.md), with support for - [inline dependency metadata](./guides/scripts.md#declaring-script-dependencies). -- ๐Ÿ—‚๏ธ Provides [comprehensive project management](./guides/projects.md), with a - [universal lockfile](./concepts/projects.md#lockfile). -- ๐Ÿข Supports Cargo-style [workspaces](./concepts/workspaces.md) for scalable projects. -- ๐Ÿ’พ Disk-space efficient, with a [global cache](./concepts/cache.md) for dependency deduplication. -- โฌ Installable without Rust or Python via `curl` or `pip`. -- ๐Ÿ–ฅ๏ธ Supports macOS, Linux, and Windows. +- ๐Ÿš€ 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](./guides/install-python.md) Python versions. +- ๐Ÿ› ๏ธ [Runs and installs](./guides/tools.md) Python applications. +- โ‡๏ธ [Runs scripts](./guides/scripts.md), with support for + [inline dependency metadata](./guides/scripts.md#declaring-script-dependencies). +- ๐Ÿ—‚๏ธ Provides [comprehensive project management](./guides/projects.md), with a + [universal lockfile](./concepts/projects.md#lockfile). +- ๐Ÿข Supports Cargo-style [workspaces](./concepts/workspaces.md) for scalable projects. +- ๐Ÿ’พ Disk-space efficient, with a [global cache](./concepts/cache.md) 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). diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md index d5ed284869468..0e4a09553b369 100644 --- a/docs/pip/compatibility.md +++ b/docs/pip/compatibility.md @@ -97,11 +97,11 @@ the specifier, since it was provided as a direct dependency. As compared to pip, the main differences in observed behavior are as follows: -- In general, local versions must be provided as direct dependencies. Resolution may succeed for - transitive dependencies that request a non-local version, but this is not guaranteed. -- If _only_ local versions exist for a package `foo` at a given version (e.g., `1.2.3+local` exists, - but `1.2.3` does not), `uv pip install foo==1.2.3` will fail, while `pip install foo==1.2.3` will - resolve to an arbitrary local version. +- In general, local versions must be provided as direct dependencies. Resolution may succeed for + transitive dependencies that request a non-local version, but this is not guaranteed. +- If _only_ local versions exist for a package `foo` at a given version (e.g., `1.2.3+local` + exists, but `1.2.3` does not), `uv pip install foo==1.2.3` will fail, while + `pip install foo==1.2.3` will resolve to an arbitrary local version. ## Packages that exist on multiple indexes @@ -137,13 +137,13 @@ As of v0.1.39, users can opt in to `pip`-style behavior for multiple indexes via `--index-strategy` command-line option, or the `UV_INDEX_STRATEGY` environment variable, which supports the following values: -- `first-match` (default): Search for each package across all indexes, limiting the candidate - versions to those present in the first index that contains the package, prioritizing the - `--extra-index-url` indexes over the default index URL. -- `unsafe-first-match`: Search for each package across all indexes, but prefer the first index with - a compatible version, even if newer versions are available on other indexes. -- `unsafe-best-match`: Search for each package across all indexes, and select the best version from - the combined set of candidate versions. +- `first-match` (default): Search for each package across all indexes, limiting the candidate + versions to those present in the first index that contains the package, prioritizing the + `--extra-index-url` indexes over the default index URL. +- `unsafe-first-match`: Search for each package across all indexes, but prefer the first index + with a compatible version, even if newer versions are available on other indexes. +- `unsafe-best-match`: Search for each package across all indexes, and select the best version + from the combined set of candidate versions. While `unsafe-best-match` is the closest to `pip`'s behavior, it exposes users to the risk of "dependency confusion" attacks. @@ -277,12 +277,12 @@ too loose, and that the user should consider tightening them. For example, in th At present, `uv pip check` will surface the following diagnostics: -- A package has no `METADATA` file, or the `METADATA` file can't be parsed. -- A package has a `Requires-Python` that doesn't match the Python version of the running - interpreter. -- A package has a dependency on a package that isn't installed. -- A package has a dependency on a package that's installed, but at an incompatible version. -- Multiple versions of a package are installed in the virtual environment. +- A package has no `METADATA` file, or the `METADATA` file can't be parsed. +- A package has a `Requires-Python` that doesn't match the Python version of the running + interpreter. +- A package has a dependency on a package that isn't installed. +- A package has a dependency on a package that's installed, but at an incompatible version. +- Multiple versions of a package are installed in the virtual environment. In some cases, `uv pip check` will surface diagnostics that `pip check` does not, and vice versa. For example, unlike `uv pip check`, `pip check` will _not_ warn when multiple versions of a package @@ -343,9 +343,9 @@ does support a large subset. Missing options and subcommands are prioritized based on user demand and the complexity of the implementation, and tend to be tracked in individual issues. For example: -- [`--prefix`](https://github.com/astral-sh/uv/issues/3076) -- [`--trusted-host`](https://github.com/astral-sh/uv/issues/1339) -- [`--user`](https://github.com/astral-sh/uv/issues/2077) +- [`--prefix`](https://github.com/astral-sh/uv/issues/3076) +- [`--trusted-host`](https://github.com/astral-sh/uv/issues/1339) +- [`--user`](https://github.com/astral-sh/uv/issues/2077) If you encounter a missing option or subcommand, please search the issue tracker to see if it has already been reported, and if not, consider opening a new issue. Feel free to upvote any existing diff --git a/docs/pip/environments.md b/docs/pip/environments.md index 59b0b486ed424..580e6423f8f50 100644 --- a/docs/pip/environments.md +++ b/docs/pip/environments.md @@ -100,23 +100,23 @@ dependencies into the environment and (2) build source distributions. When running a command that mutates an environment such as `uv pip sync` or `uv 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. +- 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`. If the `--system` flag is included, uv will skip virtual environments and search for: -- 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. +- 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. If a specific Python version is requested, e.g., `--python 3.7`, additional executable names are included: -- The Python interpreter available as, e.g., `python3.7` on macOS and Linux. +- The Python interpreter available as, e.g., `python3.7` on macOS and Linux. When running a command that does not mutate the environment such as `uv pip compile`, uv does not _require_ a virtual environment. Instead, it needs a Python toolchain to create ephemeral diff --git a/docs/pip/index.md b/docs/pip/index.md index 6b0df8fc08197..cefd8f14dc2dd 100644 --- a/docs/pip/index.md +++ b/docs/pip/index.md @@ -8,11 +8,11 @@ functionality of uv to power users and projects that are not ready to transition The following sections discuss the basics of using `uv pip`: -- [Creating and using environments](./environments.md) -- [Installing and managing packages](./packages.md) -- [Inspecting environments and packages](./inspection.md) -- [Declaring package dependencies](./dependencies.md) -- [Locking and syncing environments](./compile.md) +- [Creating and using environments](./environments.md) +- [Installing and managing packages](./packages.md) +- [Inspecting environments and packages](./inspection.md) +- [Declaring package dependencies](./dependencies.md) +- [Locking and syncing environments](./compile.md) Please note these commands do not _exactly_ implement the interfaces and behavior of the tools they are based on. The further you stray from common workflows, the more likely you are to encounter diff --git a/docs/platforms.md b/docs/platforms.md index 952c75c2ef1a8..84521e349d8d0 100644 --- a/docs/platforms.md +++ b/docs/platforms.md @@ -2,10 +2,10 @@ uv has Tier 1 support for the following platforms: -- macOS (Apple Silicon) -- macOS (x86_64) -- Linux (x86_64) -- Windows (x86_64) +- 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 @@ -15,12 +15,12 @@ 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) +- 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