From e6f16b6e539df88ef04c223355d5dd18a5050bd1 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Wed, 12 Jun 2024 08:48:31 -0500 Subject: [PATCH] Restructure the documentation --- PIP_COMPATIBILITY.md | 4 - docs/.gitignore | 1 + docs/SUMMARY.md | 49 +++ docs/book.toml | 9 + docs/cache.md | 34 ++ docs/configuration/authentication.md | 68 +++ docs/configuration/environment.md | 87 ++++ docs/configuration/files.md | 45 ++ docs/first-steps.md | 13 + docs/{ => guides}/docker.md | 15 +- docs/guides/github.md | 1 + docs/guides/pre-commit.md | 45 ++ docs/installation.md | 65 +++ docs/introduction.md | 73 ++++ docs/pip/compatibility.md | 391 ++++++++++++++++++ docs/pip/compile.md | 138 +++++++ docs/pip/dependencies.md | 44 ++ docs/pip/environments.md | 89 ++++ docs/pip/inspection.md | 41 ++ docs/pip/packages.md | 120 ++++++ docs/platforms.md | 30 ++ .../dependencies.md} | 11 +- docs/preview/introduction.md | 9 + docs/preview/projects.md | 3 + docs/preview/toolchains.md | 117 ++++++ docs/preview/tools.md | 7 + docs/{ => preview}/workspaces.md | 15 +- docs/python.md | 1 + docs/python/discovery.md | 45 ++ docs/resolution.md | 144 +++++++ docs/style.css | 42 ++ docs/theme/favicon.ico | Bin 0 -> 4286 bytes docs/theme/favicon.svg | 4 + docs/versioning.md | 9 + 34 files changed, 1749 insertions(+), 20 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/SUMMARY.md create mode 100644 docs/book.toml create mode 100644 docs/cache.md create mode 100644 docs/configuration/authentication.md create mode 100644 docs/configuration/environment.md create mode 100644 docs/configuration/files.md create mode 100644 docs/first-steps.md rename docs/{ => guides}/docker.md (89%) create mode 100644 docs/guides/github.md create mode 100644 docs/guides/pre-commit.md create mode 100644 docs/installation.md create mode 100644 docs/introduction.md create mode 100644 docs/pip/compatibility.md create mode 100644 docs/pip/compile.md create mode 100644 docs/pip/dependencies.md create mode 100644 docs/pip/environments.md create mode 100644 docs/pip/inspection.md create mode 100644 docs/pip/packages.md create mode 100644 docs/platforms.md rename docs/{specifying_dependencies.md => preview/dependencies.md} (97%) create mode 100644 docs/preview/introduction.md create mode 100644 docs/preview/projects.md create mode 100644 docs/preview/toolchains.md create mode 100644 docs/preview/tools.md rename docs/{ => preview}/workspaces.md (80%) create mode 100644 docs/python.md create mode 100644 docs/python/discovery.md create mode 100644 docs/resolution.md create mode 100644 docs/style.css create mode 100644 docs/theme/favicon.ico create mode 100644 docs/theme/favicon.svg create mode 100644 docs/versioning.md diff --git a/PIP_COMPATIBILITY.md b/PIP_COMPATIBILITY.md index 0eab394047f9..7a52f51f3e59 100644 --- a/PIP_COMPATIBILITY.md +++ b/PIP_COMPATIBILITY.md @@ -385,7 +385,3 @@ By default, uv does not write any index URLs to the output file, while `pip-comp `--index-url` or `--extra-index-url` that does not match the default (PyPI). To include index URLs in the output file, pass the `--emit-index-url` flag to `uv pip compile`. Unlike `pip-compile`, uv will include all index URLs when `--emit-index-url` is passed, including the default index URL. - -By default, uv does not write any `--no-build` or `--only-binary` options to the output file, unlike -`pip-compile`. To include these options in the output file, pass the `--emit-build-options` flag to -`uv pip compile`. diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000000..7585238efedf --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 000000000000..4df45b37f7f3 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,49 @@ +# Summary + +- [Introduction](introduction.md) + +# Getting started + +- [Installing uv](installation.md) +- [First steps](first-steps.md) + +# Basic concepts + +- [Python environments](pip/environments.md) +- [Managing packages](pip/packages.md) +- [Inspecting packages](pip/inspection.md) +- [Declaring dependencies](pip/dependencies.md) +- [Locking environments](pip/compile.md) + +# Advanced concepts + +- [Python discovery](python/discovery.md) +- [Resolution](resolution.md) +- [Caching](cache.md) +- [Authentication](configuration/authentication.md) + +# Configuration + +- [Configuration files](configuration/files.md) +- [Environment variables](configuration/environment.md) + +# Integration guides + +- [Using in Docker](guides/docker.md) +- [Using in GitHub Actions](guides/github.md) +- [Using in pre-commit](guides/pre-commit.md) + +# Preview features + +- [Introduction](preview/introduction.md) +- [Projects](preview/projects.md) +- [Dependency specification](preview/dependencies.md) +- [Workspaces](preview/workspaces.md) +- [Command-line tools](preview/tools.md) +- [Python toolchains](preview/toolchains.md) + +# Policies + +- [Versioning](versioning.md) +- [Platform support](platforms.md) +- [Compatibility with pip](pip/compatibility.md) diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 000000000000..c0832dca1d1a --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,9 @@ +[book] +language = "en" +multilingual = false +src = "." +title = "uv" + +[output.html] +no-section-label = true +additional-css = ["style.css"] diff --git a/docs/cache.md b/docs/cache.md new file mode 100644 index 000000000000..0b62f49fa2a8 --- /dev/null +++ b/docs/cache.md @@ -0,0 +1,34 @@ +# Caching + +## Dependency caching + +uv uses aggressive caching to avoid re-downloading (and re-building dependencies) that have +already been accessed in prior runs. + +The specifics of uv's caching semantics vary based on the nature of the dependency: + +- **For registry dependencies** (like those downloaded from PyPI), uv respects HTTP caching headers. +- **For direct URL dependencies**, uv respects HTTP caching headers, and also caches based on + the URL itself. +- **For Git dependencies**, uv caches based on the fully-resolved Git commit hash. As such, + `uv pip compile` will pin Git dependencies to a specific commit hash when writing the resolved + dependency set. +- **For local dependencies**, uv caches based on the last-modified time of the source archive (i.e., + the local `.whl` or `.tar.gz` file). For directories, uv caches based on the last-modified time of + the `pyproject.toml`, `setup.py`, or `setup.cfg` file. + +It's safe to run multiple `uv` commands concurrently, even against the same virtual environment. +uv's cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent +readers and writers. uv applies a file-based lock to the target virtual environment when installing, +to avoid concurrent modifications across processes. + +Note that it's _not_ safe to modify the uv cache directly (e.g., `uv cache clean`) while other `uv` +commands are running, and _never_ safe to modify the cache directly (e.g., by removing a file or +directory). + +If you're running into caching issues, uv includes a few escape hatches: + +- To force uv to revalidate cached data for all dependencies, run `uv pip install --refresh ...`. +- To force uv to revalidate cached data for a specific dependency, run, e.g., `uv pip install --refresh-package flask ...`. +- To force uv to ignore existing installed versions, run `uv pip install --reinstall ...`. +- To clear the global cache entirely, run `uv cache clean`. diff --git a/docs/configuration/authentication.md b/docs/configuration/authentication.md new file mode 100644 index 000000000000..a5d89c2f1b86 --- /dev/null +++ b/docs/configuration/authentication.md @@ -0,0 +1,68 @@ +# Authentication + +## Git authentication + +uv allows packages to be installed from Git and supports the following schemes for authenticating 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.com-key-2/astral-sh/uv`) + +See the [GitHub SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) for more details on how to configure SSH. + +Using a password or token: + +- `git+https://:@/...` (e.g. `git+https://git:github_pat_asdf@github.com/astral-sh/uv`) +- `git+https://@/...` (e.g. `git+https://github_pat_asdf@github.com/astral-sh/uv`) +- `git+https://@/...` (e.g. `git+https://git@github.com/astral-sh/uv`) + +When using a GitHub personal access token, the username is arbitrary. GitHub does not support logging in with password directly, although other hosts may. If a username is provided without credentials, you will be prompted to enter them. + +If there are no credentials present in the URL and authentication is needed, the [Git credential helper](https://git-scm.com/doc/credential-helpers) will be queried. + +## HTTP authentication + +uv supports credentials over HTTP when querying package registries. + +Authentication can come from the following sources, in order of precedence: + +- The URL, e.g., `https://:@/...` +- A [`netrc`](https://everything.curl.dev/usingcurl/netrc) configuration file +- A [keyring](https://github.com/jaraco/keyring) provider (requires opt-in) + +If authentication is found for a single net location (scheme, host, and port), it will be cached for the duration +of the command and used for other queries to that net location. Authentication is not cached across invocations of +uv. + +Note `--keyring-provider subprocess` or `UV_KEYRING_PROVIDER=subprocess` must be provided to enable keyring-based +authentication. + +Authentication may be used for hosts specified in the following contexts: + +- `index-url` +- `extra-index-url` +- `find-links` +- `package @ https://...` + +See the [`pip` compatibility guide](./pip/compatibility.md#registry-authentication) for details on differences from +`pip`. + +## Custom CA certificates + +By default, uv loads certificates from the bundled `webpki-roots` crate. The `webpki-roots` are a +reliable set of trust roots from Mozilla, and including them in uv improves portability and +performance (especially on macOS, where reading the system trust store incurs a significant delay). + +However, in some cases, you may want to use the platform's native certificate store, especially if +you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your +system's certificate store. To instruct uv to use the system's trust store, run uv with the +`--native-tls` command-line flag, or set the `UV_NATIVE_TLS` environment variable to `true`. + +If a direct path to the certificate is required (e.g., in CI), set the `SSL_CERT_FILE` environment +variable to the path of the certificate bundle, to instruct uv to use that file instead of the +system's trust store. + +If client certificate authentication (mTLS) is desired, set the `SSL_CLIENT_CERT` environment +variable to the path of the PEM formatted file containing the certificate followed by the private key. diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md new file mode 100644 index 000000000000..93f81bd9c5b3 --- /dev/null +++ b/docs/configuration/environment.md @@ -0,0 +1,87 @@ +# Environment variables + +uv accepts the following command-line arguments as environment variables: + +- `UV_INDEX_URL`: Equivalent to the `--index-url` command-line argument. If set, uv will use this + URL as the base index for searching for packages. +- `UV_EXTRA_INDEX_URL`: Equivalent to the `--extra-index-url` command-line argument. If set, uv + will use this space-separated list of URLs as additional indexes when searching for packages. +- `UV_CACHE_DIR`: Equivalent to the `--cache-dir` command-line argument. If set, uv will use this + directory for caching instead of the default cache directory. +- `UV_NO_CACHE`: Equivalent to the `--no-cache` command-line argument. If set, uv will not use the + cache for any operations. +- `UV_RESOLUTION`: Equivalent to the `--resolution` command-line argument. For example, if set to + `lowest-direct`, uv will install the lowest compatible versions of all direct dependencies. +- `UV_PRERELEASE`: Equivalent to the `--prerelease` command-line argument. For example, if set to + `allow`, uv will allow pre-release versions for all dependencies. +- `UV_SYSTEM_PYTHON`: Equivalent to the `--system` command-line argument. If set to `true`, uv + will use the first Python interpreter found in the system `PATH`. + WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI) or + containerized environments and should be used with caution, as modifying the system Python + can lead to unexpected behavior. +- `UV_PYTHON`: Equivalent to the `--python` command-line argument. If set to a path, uv will + use this Python interpreter for all operations. +- `UV_BREAK_SYSTEM_PACKAGES`: Equivalent to the `--break-system-packages` command-line argument. If + set to `true`, uv will allow the installation of packages that conflict with system-installed + packages. + WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration (CI) or + containerized environments and should be used with caution, as modifying the system Python + can lead to unexpected behavior. +- `UV_NATIVE_TLS`: Equivalent to the `--native-tls` command-line argument. If set to `true`, uv + will use the system's trust store instead of the bundled `webpki-roots` crate. +- `UV_INDEX_STRATEGY`: Equivalent to the `--index-strategy` command-line argument. For example, if + set to `unsafe-any-match`, uv will consider versions of a given package available across all + index URLs, rather than limiting its search to the first index URL that contains the package. +- `UV_REQUIRE_HASHES`: Equivalent to the `--require-hashes` command-line argument. If set to `true`, + uv will require that all dependencies have a hash specified in the requirements file. +- `UV_CONSTRAINT`: Equivalent to the `--constraint` command-line argument. If set, uv will use this + file as the constraints file. Uses space-separated list of files. +- `UV_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). diff --git a/docs/configuration/files.md b/docs/configuration/files.md new file mode 100644 index 000000000000..019049801584 --- /dev/null +++ b/docs/configuration/files.md @@ -0,0 +1,45 @@ +# Configuration files + +uv supports persistent configuration files at both the project- and user-level. + +Specifically, uv will search for a `pyproject.toml` or `uv.toml` file in the current directory, or +in the nearest parent directory. + +If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table. +For example, to set a persistent index URL, add the following to a `pyproject.toml`: + +```toml +[tool.uv.pip] +index-url = "https://test.pypi.org/simple" +``` + +(If there is no such table, the `pyproject.toml` file will be ignored, and uv will continue searching in +the directory hierarchy.) + +If a `uv.toml` file is found, uv will read from the `[pip]` table. For example: + +```toml +[pip] +index-url = "https://test.pypi.org/simple" +``` + +uv will also discover user-level configuration at `~/.config/uv/uv.toml` (or +`$XDG_CONFIG_HOME/uv/uv.toml`) on macOS and Linux, or `%APPDATA%\uv\uv.toml` on Windows. User-level +configuration must use the `uv.toml` format, rather than the `pyproject.toml` format, as a +`pyproject.toml` is intended to define a Python _project_. + +If both project- and user-level configuration are found, the settings will be merged, with the +project-level configuration taking precedence. Specifically, if a string, number, or boolean is +present in both tables, the project-level value will be used, and the user-level value will be +ignored. If an array is present in both tables, the arrays will be concatenated, with the +project-level settings appearing earlier in the merged array. + +Settings provided via environment variables take precedence over persistent configuration, and +settings provided via the command line take precedence over both. + +uv accepts a `--isolated` command-line argument which, when provided, disables the discovery of any +persistent configuration. + +uv also accepts a `--config-file` command-line argument, which accepts a path to a `uv.toml` to use +as the configuration file. When provided, this file will be used in place of _any_ discovered +configuration files (e.g., user-level configuration will be ignored). diff --git a/docs/first-steps.md b/docs/first-steps.md new file mode 100644 index 000000000000..d55e57de46e0 --- /dev/null +++ b/docs/first-steps.md @@ -0,0 +1,13 @@ +# First steps with uv + +## Check the version + +After [installing uv](./installation.md), check that it works from the CLI: + +```bash +uv version +``` + +The installed version should be displayed. + + diff --git a/docs/docker.md b/docs/guides/docker.md similarity index 89% rename from docs/docker.md rename to docs/guides/docker.md index 9e1cf3e05ca0..4df5d4f9a60d 100644 --- a/docs/docker.md +++ b/docs/guides/docker.md @@ -1,8 +1,16 @@ # Using uv in Docker +## Running in Docker + +A Docker image is published with a built version of uv available. To run a uv command in a container: + +```bash +docker run ghcr.io/astral-sh/uv --help +``` + ## Installing uv -uv can be installed by copying from our Docker image: +uv can be installed by copying from the official Docker image: ```dockerfile FROM ghcr.io/astral-sh/uv:latest as uv @@ -10,13 +18,14 @@ FROM python:3.12-slim-bullseye COPY --from=uv /uv /bin/uv ``` -Or with our standalone installer: +Or with the standalone installer: ```dockerfile FROM python:3.12-slim-bullseye RUN apt-get update && apt-get install -y curl --no-install-recommends RUN curl -LsSf https://astral.sh/uv/install.sh | sh -ENV PATH="/root/.cargo/bin/:$PATH" +ENV PATH="/root/.cargo/bin/: +$PATH" ``` Note this requires `curl` to be available. diff --git a/docs/guides/github.md b/docs/guides/github.md new file mode 100644 index 000000000000..ae8612c109d7 --- /dev/null +++ b/docs/guides/github.md @@ -0,0 +1 @@ +# Using uv in GitHub Actions diff --git a/docs/guides/pre-commit.md b/docs/guides/pre-commit.md new file mode 100644 index 000000000000..74a1b9d94fc3 --- /dev/null +++ b/docs/guides/pre-commit.md @@ -0,0 +1,45 @@ +# Using uv in pre-commit + +An official pre-commit hook is provided at [`astral-sh/uv-pre-commit`](https://github.com/astral-sh/uv-pre-commit). + +To compile requirements via pre-commit, add the following to the `.pre-commit-config.yaml`: + +```yaml +- repo: https://github.com/astral-sh/uv-pre-commit + # uv version. + rev: 0.2.13 + hooks: + # Compile requirements + - id: pip-compile + args: [requirements.in, -o, requirements.txt] +``` + +To compile alternative files, modify `args` and `files`: + +```yaml +- repo: https://github.com/astral-sh/uv-pre-commit + # uv version. + rev: 0.2.13 + hooks: + # 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: + +```yaml +- repo: https://github.com/astral-sh/uv-pre-commit + # uv version. + rev: 0.2.13 + 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)$ +``` diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 000000000000..adda1ac6c918 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,65 @@ +# Installing uv + +Install uv with our standalone installers, from PyPI, or from your package manager of choice. + +## Standalone installer + +uv provides a standalone installer that downloads and installs uv: + +```bash +# On macOS and Linux. +curl -LsSf https://astral.sh/uv/install.sh | sh + +# On Windows. +powershell -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +uv is installed to `~/.cargo/bin`. + +A specific release can be requested by including the version in the URL: + +```bash +# On macOS and Linux. +curl -LsSf https://astral.sh/uv/0.2.11/install.sh | sh + +# On Windows. +powershell -c "irm https://astral.sh/uv/0.2.11/install.ps1 | iex" +``` + +When the standalone installer is used, uv can upgrade itself. + +```bash +uv self update +``` + +Note when all other installers are used, self updates are disabled. + +## PyPI + +For convenience, uv is published to [PyPI](https://pypi.org/project/uv/). When installed from PyPI, uv can be built from source but there are prebuilt distributions (wheels) for many platforms. + +If installing from PyPI, we recommend using `pipx` to install uv into an isolated environment: + +```bash +pipx install uv +``` + +However, `pip` can also be used: + +```bash +pip install uv +``` + +## Homebrew + +uv is available in the core Homebrew packages. + +```bash +brew install uv +``` + +## Docker + +uv provides a Docker image at [`ghcr.io/astral-sh/uv`](https://github.com/astral-sh/uv/pkgs/container/uv). + +See our guide on [using uv in Docker](./guides/docker.md) for more details. diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 000000000000..cd179b1f7a46 --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,73 @@ +[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv) +[![image](https://img.shields.io/pypi/v/uv.svg)](https://pypi.python.org/pypi/uv) +[![image](https://img.shields.io/pypi/l/uv.svg)](https://pypi.python.org/pypi/uv) +[![image](https://img.shields.io/pypi/pyversions/uv.svg)](https://pypi.python.org/pypi/uv) +[![Actions status](https://github.com/astral-sh/uv/actions/workflows/ci.yml/badge.svg)](https://github.com/astral-sh/uv/actions) +[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white)](https://discord.gg/astral-sh) + +An extremely fast Python package installer and resolver, written in Rust. Designed as a drop-in +replacement for common `pip` and `pip-tools` workflows. + +

+ + + + Shows a bar chart with benchmark results. + +

+ +

+ Installing the Trio dependencies with a warm cache. +

+ +## 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, multi-platform resolutions, reproducible resolutions, + alternative resolution strategies, and more. +- โ‰๏ธ 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). + +## Getting started + +Install uv with our official standalone installer: + +```bash +# On macOS and Linux. +curl -LsSf https://astral.sh/uv/install.sh | sh + +# On Windows. +powershell -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +Or, see our [installation guide](./installation.md) for more options. + +Then, check out our documentation [creating an environment](pip/environments.html). + +## Features + +uv supports features familiar from `pip` and `pip-tools`: + +- [Managing Python environments](pip/environments.md) +- [Installing packages](pip/basics.md) +- [Inspecting packages](pip/inspection.md) +- [Locking environments](pip/compile.md) + +uv also supports many advanced features: + +- [Multi-platform resolution](./resolution.md#multi-platform-resolution) +- [Dependency overrides](./resolution.md#dependency-overrides) +- [Reproducible resolutions](./resolution.md#time-restricted-reproducible-resolutions) +- [Resolution strategies for multiple indexes](./resolution.md#resolution-strategy) +- [Dependency caching](./cache.md#dependency-caching) diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md new file mode 100644 index 000000000000..0eab394047f9 --- /dev/null +++ b/docs/pip/compatibility.md @@ -0,0 +1,391 @@ +# Compatibility with `pip` and `pip-tools` + +uv is designed as a drop-in replacement for common `pip` and `pip-tools` workflows. + +Informally, the intent is such that existing `pip` and `pip-tools` users can switch to uv without +making meaningful changes to their packaging workflows; and, in most cases, swapping out +`pip install` for `uv pip install` should "just work". + +However, uv is _not_ intended to be an _exact_ clone of `pip`, and the further you stray from +common `pip` workflows, the more likely you are to encounter differences in behavior. In some cases, +those differences may be known and intentional; in others, they may be the result of implementation +details; and in others, they may be bugs. + +This document outlines the known differences between uv and `pip`, along with rationale, +workarounds, and a statement of intent for compatibility in the future. + +## Configuration files and environment variables + +uv does not read configuration files or environment variables that are specific to `pip`, like +`pip.conf` or `PIP_INDEX_URL`. + +Reading configuration files and environment variables intended for other tools has a number of +drawbacks: + +1. It requires bug-for-bug compatibility with the target tool, since users end up relying on bugs in + the format, the parser, etc. +2. If the target tool _changes_ the format in some way, uv is then locked-in to changing it in + equivalent ways. +3. If that configuration is versioned in some way, uv would need to know _which version_ of the + target tool the user is expecting to use. +4. It prevents uv from introducing any settings or configuration that don't exist in the target + tool, since otherwise `pip.conf` (or similar) would no longer be usable with `pip`. +5. It can lead to user confusion, since uv would be reading settings that don't actually affect its + behavior, and many users may _not_ expect uv to read configuration files intended for other + tools. + +Instead, uv supports its own environment variables, like `UV_INDEX_URL`. In the future, uv will +also support persistent configuration in its own configuration file format (e.g., `pyproject.toml` +or `uv.toml` or similar). For more, see [#651](https://github.com/astral-sh/uv/issues/651). + +## Pre-release compatibility + +By default, uv will accept pre-release versions during dependency resolution in two cases: + +1. If the package is a direct dependency, and its version markers include a pre-release specifier + (e.g., `flask>=2.0.0rc1`). +1. If _all_ published versions of a package are pre-releases. + +If dependency resolution fails due to a transitive pre-release, uv will prompt the user to +re-run with `--prerelease=allow`, to allow pre-releases for all dependencies. + +Alternatively, you can add the transitive dependency to your `requirements.in` file with +pre-release specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific +dependency. + +In sum, uv needs to know upfront whether the resolver should accept pre-releases for a given +package. `pip`, meanwhile, _may_ respect pre-release identifiers in transitive dependencies +depending on the order in which the resolver encounters the relevant specifiers ([#1641](https://github.com/astral-sh/uv/issues/1641#issuecomment-1981402429)). + +Pre-releases are [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) +to model, and are a frequent source of bugs in packaging tools. Even `pip`, which is viewed as a +reference implementation, has a number of open questions around pre-release handling ([#12469](https://github.com/pypa/pip/issues/12469), +[#12470](https://github.com/pypa/pip/issues/12470), [#40505](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/20), etc.). +uv's pre-release handling is _intentionally_ limited and _intentionally_ requires user opt-in for +pre-releases, to ensure correctness. + +In the future, uv _may_ support pre-release identifiers in transitive dependencies. However, it's +likely contingent on evolution in the Python packaging specifications. The existing PEPs [do not +cover "dependency resolution"](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/17) +and are instead focused on behavior for a _single_ version specifier. As such, there are unresolved +questions around the correct and intended behavior for pre-releases in the packaging ecosystem more +broadly. + +## Local version identifiers + +uv does not implement spec-compliant handling of local version identifiers (e.g., `1.2.3+local`). +This is considered a known limitation. Although local version identifiers are rare in published +packages (and, e.g., disallowed on PyPI), they're common in the PyTorch ecosystem, and uv's approach +to local versions _does_ support typical PyTorch workflows to succeed out-of-the-box. + +[PEP 440](https://peps.python.org/pep-0440/#version-specifiers) specifies that the local version +segment should typically be ignored when evaluating version specifiers, with a few exceptions. +For example, `foo==1.2.3` should accept `1.2.3+local`, but `foo==1.2.3+local` should _not_ accept +`1.2.3`. These asymmetries are hard to model in a resolution algorithm. As such, uv treats `1.2.3` +and `1.2.3+local` as entirely separate versions, but respects local versions provided as direct +dependencies throughout the resolution, such that if you provide `foo==1.2.3+local` as a direct +dependency, `1.2.3+local` _will_ be accepted for any transitive dependencies that request +`foo==1.2.3`. + +To take an example from the PyTorch ecosystem, it's common to specify `torch==2.0.0+cu118` and +`torchvision==0.15.1+cu118` as direct dependencies. `torchvision @ 0.15.1+cu118` declares a +dependency on `torch==2.0.0`. In this case, uv would recognize that `torch==2.0.0+cu118` satisfies +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. + +## Packages that exist on multiple indexes + +In both uv and `pip`, users can specify multiple package indexes from which to search for +the available versions of a given package. However, uv and `pip` differ in how they handle +packages that exist on multiple indexes. + +For example, imagine that a company publishes an internal version of `requests` on a private index +(`--extra-index-url`), but also allows installing packages from PyPI by default. In this case, the +private `requests` would conflict with the public [`requests`](https://pypi.org/project/requests/) +on PyPI. + +When uv searches for a package across multiple indexes, it will iterate over the indexes in order +(preferring the `--extra-index-url` over the default index), and stop searching as soon as it +finds a match. This means that if a package exists on multiple indexes, uv will limit its +candidate versions to those present in the first index that contains the package. + +`pip`, meanwhile, will combine the candidate versions from all indexes, and select the best +version from the combined set, though it makes [no guarantees around the order](https://github.com/pypa/pip/issues/5045#issuecomment-369521345) +in which it searches indexes, and expects that packages are unique up to name and version, even +across indexes. + +uv's behavior is such that if a package exists on an internal index, it should always be installed +from the internal index, and never from PyPI. The intent is to prevent "dependency confusion" +attacks, in which an attacker publishes a malicious package on PyPI with the same name as an +internal package, thus causing the malicious package to be installed instead of the internal +package. See, for example, [the `torchtriton` attack](https://pytorch.org/blog/compromised-nightly-dependency/) +from December 2022. + +As of v0.1.39, users can opt in to `pip`-style behavior for multiple indexes via the +`--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. + +While `unsafe-best-match` is the closest to `pip`'s behavior, it exposes users to the risk of +"dependency confusion" attacks. + +In the future, uv will support pinning packages to dedicated indexes (see: [#171](https://github.com/astral-sh/uv/issues/171)). +Additionally, [PEP 708](https://peps.python.org/pep-0708/) is a provisional standard that aims to +address the "dependency confusion" issue across package registries and installers. + +## Transitive direct URL dependencies for constraints and overrides + +While uv does support URL dependencies (e.g., `black @ https://...`), it does not support +_transitive_ (i.e., "nested") direct URL dependencies for constraints and overrides. + +Specifically, if a constraint or override is defined using a direct URL dependency, and the +constrained package has a direct URL dependency of its own, uv _may_ reject that transitive direct +URL dependency during resolution. + +uv also makes the assumption that non-URL dependencies won't introduce URL dependencies (i.e., that +dependencies fetched from a registry will not themselves have direct URL dependencies). If a non-URL +dependency _does_ introduce a URL dependency, uv will reject the URL dependency during resolution. + +If uv rejects a transitive URL dependency in either case, the best course of action is to provide +the URL dependency as a direct dependency in the `requirements.in` file, rather than as a +constraint, override, or transitive dependency. + +## Virtual environments by default + +`uv pip install` and `uv pip sync` are designed to work with virtual environments by default. + +Specifically, uv will always install packages into the currently active virtual environment, or +search for a virtual environment named `.venv` in the current directory or any parent directory +(even if it is not activated). + +This differs from `pip`, which will install packages into a global environment if no virtual +environment is active, and will not search for inactive virtual environments. + +In uv, you can install into non-virtual environments by providing a path to a Python executable +via the `--python /path/to/python` option, or via the `--system` flag, which installs into the +first Python interpreter found on the `PATH`, like `pip`. + +In other words, uv inverts the default, requiring explicit opt-in to installing into the system +Python, which can lead to breakages and other complications, and should only be done in limited +circumstances. + +For more, see ["Installing into arbitrary Python environments"](./README.md#installing-into-arbitrary-python-environments). + +## Resolution strategy + +For a given set of dependency specifiers, it's often the case that there is no single "correct" +set of packages to install. Instead, there are many valid sets of packages that satisfy the +specifiers. + +Neither `pip` nor uv make any guarantees about the _exact_ set of packages that will be +installed; only that the resolution will be consistent, deterministic, and compliant with the +specifiers. As such, in some cases, `pip` and uv will yield different resolutions; however, both +resolutions _should_ be equally valid. + +For example, consider: + +```txt +# requirements.txt +starlette +fastapi +``` + +At time of writing, the most recent `starlette` version is `0.37.2`, and the most recent `fastapi` +version is `0.110.0`. However, `fastapi==0.110.0` also depends on `starlette`, and introduces an +upper bound: `starlette>=0.36.3,<0.37.0`. + +If a resolver prioritizes including the most recent version of `starlette`, it would need to use +an older version of `fastapi` that excludes the upper bound on `starlette`. In practice, this +requires falling back to `fastapi==0.1.17`: + +```txt +# This file was autogenerated by uv via the following command: +# uv pip compile - +annotated-types==0.6.0 + # via pydantic +anyio==4.3.0 + # via starlette +fastapi==0.1.17 +idna==3.6 + # via anyio +pydantic==2.6.3 + # via fastapi +pydantic-core==2.16.3 + # via pydantic +sniffio==1.3.1 + # via anyio +starlette==0.37.2 + # via fastapi +typing-extensions==4.10.0 + # via + # pydantic + # pydantic-core +``` + +Alternatively, if a resolver prioritizes including the most recent version of `fastapi`, it would +need to use an older version of `starlette` that satisfies the upper bound. In practice, this +requires falling back to `starlette==0.36.3`: + +```txt +# uv pip compile - +annotated-types==0.6.0 + # via pydantic +anyio==4.3.0 + # via starlette +fastapi==0.110.0 +idna==3.6 + # via anyio +pydantic==2.6.3 + # via fastapi +pydantic-core==2.16.3 + # via pydantic +sniffio==1.3.1 + # via anyio +starlette==0.36.3 + # via fastapi +typing-extensions==4.10.0 + # via + # fastapi + # pydantic + # pydantic-core +``` + +When uv resolutions differ from `pip` in undesirable ways, it's often a sign that the specifiers +are too loose, and that the user should consider tightening them. For example, in the case of +`starlette` and `fastapi`, the user could require `fastapi>=0.110.0`. + +## `pip check` + +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. + +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 +are installed in the current environment. + +## `--user` and the `user` install scheme + +uv does not support the `--user` flag, which installs packages based on the `user` install scheme. +Instead, we recommend the use of virtual environments to isolate package installations. + +Additionally, pip will fall back to the `user` install scheme if it detects that the user does not +have write permissions to the target directory, as is the case on some systems when installing into +the system Python. uv does not implement any such fallback. + +For more, see [#2077](https://github.com/astral-sh/uv/issues/2077). + +## `--only-binary` enforcement + +The `--only-binary` argument is used to restrict installation to pre-built binary distributions. +When `--only-binary :all:` is provided, both pip and uv will refuse to build source distributions +from PyPI and other registries. + +However, when a dependency is provided as a direct URL (e.g., `uv pip install https://...`), pip +does _not_ enforce `--only-binary`, and will build source distributions for all such packages. + +uv, meanwhile, _does_ enforce `--only-binary` for direct URL dependencies, with one exception: +given `uv pip install https://... --only-binary flask`, uv _will_ build the source distribution at +the given URL if it cannot infer the package name ahead of time, since uv can't determine whether +the package is "allowed" in such cases without building its metadata. + +Both pip and uv allow editables requirements to be built and installed even when `--only-binary` is +provided. For example, `uv pip install -e . --only-binary :all:` is allowed. + +## Bytecode compilation + +Unlike pip, uv does not compile `.py` files to `.pyc` files during installation by default (i.e., +uv does not create or populate `__pycache__` directories). To enable bytecode compilation +during installs, pass the `--compile-bytecode` flag to `uv pip install` or `uv pip sync`. + +## Strictness and spec enforcement + +uv tends to be stricter than `pip`, and will often reject packages that `pip` would install. +For example, uv omits packages with invalid version specifiers in its metadata, which `pip` +similarly plans to exclude in a [future release](https://github.com/pypa/pip/issues/12063). + +In some cases, uv implements lenient behavior for popular packages that are known to have +specific spec compliance issues. + +If uv rejects a package that `pip` would install due to a spec violation, the best course of +action is to first attempt to install a newer version of the package; and, if that fails, to report +the issue to the package maintainer. + +## `pip` command-line options and subcommands + +uv does not support the complete set of `pip`'s command-line options and subcommands, although it +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) + +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 +issues to convey your interest. + +## Registry authentication + +uv does not support `pip`'s `auto` or `import` options for `--keyring-provider`. At present, only +the `subproces` option is supported. + +Unlike `pip`, uv does not enable keyring authentication by default. + +Unlike `pip`, uv does not wait until a request returns a HTTP 401 before searching for +authentication. uv attaches authentication to all requests for hosts with credentials available. + +## `egg` support + +uv does not support features that are considered legacy or deprecated in `pip`. For example, +uv does not support `.egg`-style distributions. + +However, uv does have partial support for (1) `.egg-info`-style distributions (which are +occasionally found in Docker images and Conda environments) and (2) legacy editable +`.egg-link`-style distributions. + +Specifically, uv does not support installing new `.egg-info`- or `.egg-link`-style distributions, +but will respect any such existing distributions during resolution, list them with `uv pip list` and +`uv pip freeze`, and uninstall them with `uv pip uninstall`. + +## `pip compile` defaults + +There are a few small but notable differences in the default behaviors of `pip compile` and +`pip-tools`. + +By default, uv does not write the compiled requirements to an output file. Instead, uv requires +that the user specify an output file explicitly with the `-o` or `--output-file` option. + +By default, uv strips extras when outputting the compiled requirements. In other words, uv defaults to +`--strip-extras`, while `pip-compile` defaults to `--no-strip-extras`. `pip-compile` is scheduled to +change this default in the next major release (v8.0.0), at which point both tools will default to +`--strip-extras`. To retain extras with uv, pass the `--no-strip-extras` flag to `uv pip compile`. + +By default, uv does not write any index URLs to the output file, while `pip-compile` outputs any +`--index-url` or `--extra-index-url` that does not match the default (PyPI). To include index URLs +in the output file, pass the `--emit-index-url` flag to `uv pip compile`. Unlike `pip-compile`, +uv will include all index URLs when `--emit-index-url` is passed, including the default index URL. + +By default, uv does not write any `--no-build` or `--only-binary` options to the output file, unlike +`pip-compile`. To include these options in the output file, pass the `--emit-build-options` flag to +`uv pip compile`. diff --git a/docs/pip/compile.md b/docs/pip/compile.md new file mode 100644 index 000000000000..13eeece15899 --- /dev/null +++ b/docs/pip/compile.md @@ -0,0 +1,138 @@ +# Locking environments + +Locking is to take a dependency, e.g., `ruff`, and write an exact version to use to a file. When working with many dependencies, it is useful to lock the exact versions so the environment can be reproduced. Without locking, the versions of dependencies could change over time, when using a different tool, or across platforms. + +## Locking requirements + +uv allows dependencies to be locked in the `requirements.txt` format. It is recommended to use the standard `pyproject.toml` to define dependencies, but other dependency formats are supported as well. See the documentation on [declaring dependencies](dependencies.md) for more details on how to define dependencies. + +To lock dependencies declared in a `pyproject.toml`: + +```bash +uv pip compile pyproject.toml -o requirements.txt +``` + +Note by default the `uv pip compile` output is just displayed and `--output-file` / `-o` argument is needed to write to a file. + +To lock dependencies declared in a `requirements.in`: + +```bash +uv pip compile requirements.in -o requirements.txt +``` + +To lock dependencies declared in multiple files: + +```bash +uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt` +``` + +uv also supports legacy `setup.py` and `setup.cfg` formats. To lock dependencies declared in a `setup.py`: + +```bash +uv pip compile setup.py -o requirements.txt +``` + +To lock dependencies from stdin, use `-`: + +```bash +echo "ruff" | uv pip compile - +``` + +To lock with optional dependencies enabled, e.g., the "foo" extra: + +```bash +uv pip install -r pyproject.toml --extra foo +``` + +To lock with all optional dependencies enabled: + +```bash +uv pip install -r pyproject.toml --all-extras +``` + +Note extras are not supported with the `requirements.in` format. + +## Upgrading requirements + +When using an output file, uv will consider the versions pinned in an existing output file. If a dependency is pinned it will not be upgraded on a subsequent compile run. For example: + +```console +$ echo "ruff==0.3.0" > requirements.txt +$ echo "ruff" | uv pip compile - -o requirements.txt +# This file was autogenerated by uv via the following command: +# uv pip compile - -o requirements.txt +ruff==0.3.0 +``` + +To upgrade a dependency, use the `--upgrade-package` flag: + +```bash +uv pip compile - -o requirements.txt --upgrade-package ruff +``` + +To upgrade all dependencies, there is an `--upgrade` flag. + +## Syncing an environment + +Dependencies can be installed directly from their definition files or from compiled `requirements.txt` files with `uv pip install`. See the documentation on [installing packages from files](packages.md#installing-packages-from-files) for more details. + +When installing with `uv pip install`, packages that are already installed will not be removed unless they conflict with the lock file. This means that the environment can have dependencies that aren't declared in the lock file, which isn't great for reproducibility. To ensure the environment exactly matches the lock file, use `uv pip sync` instead. + +To sync an environment with a `requirements.txt` file: + +```shell +uv pip sync requirements.txt +``` + +To sync an environment with a `pyproject.toml` file: + +```shell +uv pip sync pyproject.toml +``` + +## Adding constraints + +Constraints files are `requirements.txt`-like files that only control the _version_ of a requirement that's installed. However, +including a package in a constraints file will _not_ trigger the installation of that package. Constraints can be used to add bounds to dependencies that are not dependencies of the current project. + +To define an constraint, define a bound for a package: + +```text +# constraints.txt +pydantic<2.0 +``` + +To use a constraint file: + +```shell +uv pip compile requirements.in --constraint constraints.txt +``` + +Note that multiple constraints can be defined in each file and multiple files can be used. + +## Overriding dependency versions + +Overrides files are `requirements.txt`-like files that force a specific version of a requirement to be installed, regardless of +the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution. + +While constraints are _additive_, in that they're combined with the requirements of the constituent packages, overrides are +_absolute_, in that they completely replace the requirements of the constituent packages. + +Overrides are most often used to remove upper bounds from a transtive dependency. For example, if `a` requires `c>=1.0,<2.0` and `b` requires `c>=2.0` and the current project requires `a` and `b` then the dependencies cannot be resolved. + +To define an override, define the new requirement for the problematic package: + +```text +# override.txt +c>=2.0 +``` + +To use an override file: + +```shell +uv pip compile requirements.in --override override.txt +``` + +Now, resolution can succeed. However, note that if `a` is _correct_ that it does not support `c>=2.0` then a runtime error will likely be encountered when using the packages. + +Note that multiple overrides can be defined in each file and multiple files can be used. diff --git a/docs/pip/dependencies.md b/docs/pip/dependencies.md new file mode 100644 index 000000000000..f090c36a2534 --- /dev/null +++ b/docs/pip/dependencies.md @@ -0,0 +1,44 @@ +# Declaring dependencies + +It is best practice to declare dependencies in a static file instead of modifying environments with ad-hoc installations. Once dependencies are defined, they can be [locked](./compile.md) to create a consistent, reproducible environment. + +## Using `pyproject.toml` + +The `pyproject.toml` file is the Python standard for defining configuration for a project. + +To define project dependencies in a `pyproject.toml` file: + +```toml +[project] +dependencies = [ + "httpx", + "ruff>=0.3.0" +] +``` + +To define optional dependencies in a `pyproject.toml` file: + +```toml +[project.optional-dependencies] +cli = [ + "rich", + "click", +] +``` + +Each of the keys defines an "extra", which can be installed using the `--extra` and `--all-extras` flags or `package[]` syntax. See the documentation on [installing packages](./packages.md#installing-packages-from-files) for more details. + +See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with a `pyproject.toml`. + +## Using `requirements.in` + +It is also common to use a lightweight `requirements.txt` format to declare the dependencies for the project. Each requirement is defined on its own line. Commonly, this file is called `requirements.in` to distinguish it from `requirements.txt` which is used for the locked dependencies. + +To define dependencies in a `requirements.in` file: + +```text +httpx +ruff>=0.3.0 +``` + +Optional dependencies groups are not supported in this format. diff --git a/docs/pip/environments.md b/docs/pip/environments.md new file mode 100644 index 000000000000..c3c2b232ba4a --- /dev/null +++ b/docs/pip/environments.md @@ -0,0 +1,89 @@ +# Python environments + +Each Python installation has an environment that is active when Python is used. Packages can be installed into an environment to make their modules available from your Python scripts. Generally, it is considered best practice not to modify a Python installation's environment. This is especially important for Python installations that come with the operating system which often manage the packages themselves. A virtual environment is a lightweight way to isolate packages from a Python installation's environment. Unlike `pip`, uv requires using a virtual environment by default. + +## Creating a virtual environment + +uv supports creating virtual environments: + +```bash +# Create a virtual environment at `.venv` +uv venv +``` + +A specific name or path can be specified: + +```bash +# Create a virtual environment at `my-name` +uv venv my-name +``` + +A Python version can be requested: + +```bash +# Create a virtual environment with Python 3.11 +uv venv --python 3.11 +``` + +Note this requires the requested Python version to be available on the system. +However, in preview mode, [uv will download Python for you](../preview/toolchains.md). +See the [python request](../python/requests.md) documentation for more details on requesting Python versions. + +## Using a virtual environment + +When using the default virtual environment name, uv will automatically find and use the virtual environment during subsequent invocations. + +```bash +uv venv + +# Install a package in the new virtual environment +uv pip install ruff +``` + +The virtual environment can be "activated" to make its packages available: + +```bash +# On macOS and Linux. +source .venv/bin/activate + +# On Windows. +.venv\Scripts\activate +``` + +## Using arbitrary Python environments + +Since uv has no dependency on Python, it can install into virtual environments other than +its own. For example, setting `VIRTUAL_ENV=/path/to/venv` will cause uv to install into +`/path/to/venv`, regardless of where uv is installed. Note that if `VIRTUAL_ENV` is set to +a directory that is **not** a [PEP 405 compliant](https://peps.python.org/pep-0405/#specification) +virtual environment, it will be ignored. + +uv can also install into arbitrary, even non-virtual environments, with the `--python` argument +provided to `uv pip sync` or `uv pip install`. For example, `uv pip install --python=/path/to/python` +will install into the environment linked to the `/path/to/python` interpreter. + +For convenience, `uv pip install --system` will install into the system Python environment. +Using `--system` is roughly equivalent to `uv pip install --python=$(which python)`, +but note that executables that are linked to virtual environments will be skipped. +Although we generally recommend using virtual environments for dependency management, +`--system` is appropriate in continuous integration and containerized environments. + +The `--system` flag is also used to opt in to mutating system environments. For example, the +the `--python` argument can be used to request a Python version (e.g., `--python 3.12`), and uv will +search for an interpreter that meets the request. If uv finds a system interpreter (e.g., `/usr/lib/python3.12`), +then the `--system` flag is required to allow modification of this non-virtual Python environment. +Without the `--system` flag, uv will ignore any interpreters that are not in virtual environments. +Conversely, when the `--system` flag is provided, uv will ignore any interpreters that _are_ +in virtual environments. + +Installing into system Python across platforms and distributions is notoriously difficult. uv +supports the common cases, but will not work in all cases. For example, installing into system +Python on Debian prior to Python 3.10 is unsupported due to the [distribution's patching +of `distutils` (but not `sysconfig`)](https://ffy00.github.io/blog/02-python-debian-and-the-install-locations/). +While we always recommend the use of virtual environments, uv considers them to be required in +these non-standard environments. + +If uv is installed in a Python environment, e.g., with `pip`, it can still be used to modify +other environments. However, when invoked with `python -m uv`, uv will default to using the parent +interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for +general usage. diff --git a/docs/pip/inspection.md b/docs/pip/inspection.md new file mode 100644 index 000000000000..41435e555b42 --- /dev/null +++ b/docs/pip/inspection.md @@ -0,0 +1,41 @@ +# Inspecting environments + +## Listing installed packages + +To list all of the packages in the environment: + +```bash +uv pip list +``` + +To list the packages in a JSON format: + +```bash +uv pip list --format json +``` + +To list all of the packages in the environment in a `requirements.txt` format: + +```bash +uv pip freeze +``` + +## Inspecting a package + +To show information about an installed package, e.g., `numpy`: + +```bash +uv pip show numpy +``` + +Multiple packages can be inspected at once. + +## Verifying an environment + +It is possible to install packages with conflicting requirements into an environment if installed in multiple steps. + +To check for conflicts or missing dependencies in the environment: + +```bash +uv pip check +``` diff --git a/docs/pip/packages.md b/docs/pip/packages.md new file mode 100644 index 000000000000..a66d69c1106b --- /dev/null +++ b/docs/pip/packages.md @@ -0,0 +1,120 @@ +# Managing packages + +## Installing a package + +To install a package into the virtual environment, e.g., Flask: + +```bash +uv pip install flask +``` + +To install a package with optional dependencies enabled, e.g., Flask with the "dotenv" extra: + +``` +uv pip install "flask[dotenv]" +``` + +To install multiple packages, e.g., Flask and Ruff: + +```bash +uv pip install flask ruff +``` + +To install a package with a constraint, e.g., Ruff v0.2.0 or newer: + +```bash +uv pip install 'ruff>=0.2.0' +``` + +To install a package at a specific version, e.g., Ruff v0.3.0: + +```bash +uv pip install 'ruff==0.3.0' +``` + +To install a package from the disk: + +```bash +uv pip install "ruff @ ./projects/ruff" +``` + +To install a package from GitHub: + +```bash +uv pip install "git+https://github.com/astral-sh/ruff" +``` + +To install a package from GitHub at a specific reference: + +```bash +# Install a tag +uv pip install "git+https://github.com/astral-sh/ruff@v0.2.0" + +# Install a commit +uv pip install "git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e6130bde2243c929d" + +# Install a branch +uv pip install "git+https://github.com/astral-sh/ruff@main" +``` + +See the [Git authentication](../configuration/authentication.md#git-authentication) documentation for installation from a private repository. + +## Editable packages + +Editable packages do not need to be reinstalled for change to their source code to be active. + +To install the current project as an editable package + +```bash +uv pip install -e . +``` + +To install a project in another directory as an editable package: + +```bash +uv pip install -e ruff @ ./project/ruff +``` + +## Installing packages from files + +Multiple packages can be installed at once from standard file formats. + +Install from a `requirements.txt` file: + +```bash +uv pip install -r requirements.txt +``` + +See the [`uv pip compile`](./compile.md) documentation for more information on `requirements.txt` files. + +Install from a `pyproject.toml` file: + +```bash +uv pip install -r pyproject.toml +``` + +Install from a `pyproject.toml` file with optional dependencies enabled, e.g., the "foo" extra: + +```bash +uv pip install -r pyproject.toml --extra foo +``` + +Install from a `pyproject.toml` file with all optional dependencies enabled: + +```bash +uv pip install -r pyproject.toml --all-extras +``` + +## Uninstalling a package + +To uninstall a package, e.g., Flask: + +```bash +uv pip uninstall flask +``` + +To uninstall multiple packages, e.g., Flask and Ruff: + +```bash +uv pip uninstall flask ruff +``` diff --git a/docs/platforms.md b/docs/platforms.md new file mode 100644 index 000000000000..68c9d2b36047 --- /dev/null +++ b/docs/platforms.md @@ -0,0 +1,30 @@ +# Platform support + +uv has Tier 1 support for the following platforms: + +- macOS (Apple Silicon) +- macOS (x86_64) +- Linux (x86_64) +- Windows (x86_64) + +uv is continuously built, tested, and developed against its Tier 1 platforms. Inspired by the +Rust project, Tier 1 can be thought of as ["guaranteed to work"](https://doc.rust-lang.org/beta/rustc/platform-support.html). + +uv has Tier 2 support (["guaranteed to build"](https://doc.rust-lang.org/beta/rustc/platform-support.html)) for the following platforms: + +- Linux (PPC64) +- Linux (PPC64LE) +- Linux (aarch64) +- Linux (armv7) +- Linux (i686) +- Linux (s390x) + +uv ships pre-built wheels to [PyPI](https://pypi.org/project/uv/) for its Tier 1 and +Tier 2 platforms. However, while Tier 2 platforms are continuously built, they are not continuously +tested or developed against, and so stability may vary in practice. + +Beyond the Tier 1 and Tier 2 platforms, uv is known to build on i686 Windows, and known _not_ +to build on aarch64 Windows, but does not consider either platform to be supported at this time. +The minimum supported Windows version is Windows 10, following [Rust's own Tier 1 support](https://blog.rust-lang.org/2024/02/26/Windows-7.html). + +uv supports and is tested against Python 3.8, 3.9, 3.10, 3.11, and 3.12. diff --git a/docs/specifying_dependencies.md b/docs/preview/dependencies.md similarity index 97% rename from docs/specifying_dependencies.md rename to docs/preview/dependencies.md index fc3f458d1248..34a90d7210ef 100644 --- a/docs/specifying_dependencies.md +++ b/docs/preview/dependencies.md @@ -1,5 +1,4 @@ -**Warning: this documentation applies to a future version of uv. Please refer to -[README.md](../README.md) for documentation for the latest release.** +**Warning: This documentation refers to experimental features that may change.** # Specifying dependencies @@ -179,10 +178,10 @@ default-dev-dependencies = ["test"] The [PEP 508](https://peps.python.org/pep-0508/) syntax allows you to specify, 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/preview/introduction.md b/docs/preview/introduction.md new file mode 100644 index 000000000000..108376bcdb60 --- /dev/null +++ b/docs/preview/introduction.md @@ -0,0 +1,9 @@ +# Introduction + +uv is expanding from low-level commands to manage virtual environments and their packages to high-level project management commands and global management of Python installations and command line tools. + +See the [project documentation](projects.md) for using uv to manage dependencies in a project, similar to `poetry`. + +See the [tool documentation](tools.md) for using uv to run tools in ephemeral environments and install tools, similar to `pipx`. + +See the [toolchain documentation](toolchains.md) for using uv to manage Python installations, similar to `pyenv`. diff --git a/docs/preview/projects.md b/docs/preview/projects.md new file mode 100644 index 000000000000..1d330ff730dc --- /dev/null +++ b/docs/preview/projects.md @@ -0,0 +1,3 @@ +**Warning: This documentation refers to experimental features that may change.** + +# Projects diff --git a/docs/preview/toolchains.md b/docs/preview/toolchains.md new file mode 100644 index 000000000000..97ecee2a2504 --- /dev/null +++ b/docs/preview/toolchains.md @@ -0,0 +1,117 @@ +**Warning: This documentation refers to experimental features that may change.** + +# Toolchains + +A Python toolchain is composed of a Python interpreter (i.e. the `python` executable), the standard library, and other supporting files. It is common for an operating system to come with a Python toolchain installed and there are many tools to help manage Python toolchains. + +## Requesting a toolchain + +uv will automatically download a toolchain if it cannot be found. + +In stable commands, this behavior requires enabling preview mode. For example, when creating a virtual environment: + +```bash +uv venv --preview --python 3.11.6 +``` + +uv will ensure that Python 3.11.6 is available โ€” downloading and installing it if necessary โ€” then create the virtual environment with it. + +For commands that are in preview, like `uv sync`, preview behavior is always on. + +```bash +uv sync --python 3.12.3 +``` + +Many toolchain 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` + +At this time, only CPython downloads are supported. However, PyPy support is planned. + +## Installing a toolchain + +Sometimes it is preferable to install the toolchains before they are needed. + +To install a toolchain at a specific version: + +```bash +uv toolchain install 3.12.3 +``` + +To install the latest patch version: + +```bash +uv toolchain install 3.12 +``` + +To install a version that satisfies constraints: + +```bash +uv toolchain install '>=3.8,<3.10' +``` + +To install multiple versions: + +```bash +uv toolchain install 3.9 3.10 3.11 +``` + +## Installing project toolchains + +By default `uv toolchain install` will verify that a managed toolchain is installed or install the latest version. + +However, a project may define a `.python-version` file specifying the default Python toolchain to be used. If present, +uv will install the toolchain listed in the file. + +Alternatively, a project that requires multiple Python versions may also define a `.python-versions` file. If present, +uv will install all of the toolchains listed in the file. This file takes precedence over the `.python-version` file. + +uv will also respect Python requirements defined in a `pyproject.toml` file during project command invocations. + +## Viewing available toolchains + +To list installed and available toolchains: + +```bash +uv toolchain list +``` + +By default, downloads for other platforms and old patch versions are hidden. + +To view all versions: + +```bash +uv toolchain list --all-versions +``` + +To view toolchains for other platforms: + +```bash +uv toolchain list --all-platforms +``` + +To exclude downloads and only show installed toolchains: + +```bash +uv toolchain list --only-installed +``` + +## Adjusting toolchain preferences + +By default, uv will attempt to use Python toolchains found on the system and only download managed interpreters when necessary. +However, It's possible to adjust uv's toolchain selection preference with the `toolchain-preference` option. + +- `only-managed`: Only use managed toolchains, never use system toolchains. +- `prefer-installed-managed`: Prefer installed managed toolchains, but use system toolchains if not found. If neither can be + found, download a managed interpreter. +- `prefer-managed`: Prefer managed toolchains, even if one needs to be downloaded, but use system toolchains if found. +- `prefer-system`: Prefer system toolchains, only use managed toolchains if no system interpreter is found. +- `only-system`: Only use system toolchains, never use managed toolchains. + +These options allow disabling uv's managed toolchains entirely or always using them and ignoring any existing system installations. diff --git a/docs/preview/tools.md b/docs/preview/tools.md new file mode 100644 index 000000000000..0d5c5a100000 --- /dev/null +++ b/docs/preview/tools.md @@ -0,0 +1,7 @@ +**Warning: This documentation refers to experimental features that may change.** + +# Command-line tools + +## Running a tool + +## Installing a tool diff --git a/docs/workspaces.md b/docs/preview/workspaces.md similarity index 80% rename from docs/workspaces.md rename to docs/preview/workspaces.md index b162524b5a0e..49737dba393b 100644 --- a/docs/workspaces.md +++ b/docs/preview/workspaces.md @@ -1,17 +1,18 @@ -**Warning: this documentation applies to a future version of uv. Please refer to -[README.md](../README.md) for documentation for the latest release.** +**Warning: This documentation refers to experimental features that may change.** -Workspaces help you organize large codebases by splitting them into multiple packages with +# Workspaces + +Workspaces help organize large codebases by splitting them into multiple packages with independent dependencies. When using the `uv pip` interface, workspace dependencies behave like automatic editable path -dependencies. Using the `uv` interface, all your workspace packages are locked together. `uv run` -installs only the current package (unless overridden with `--package`) and its workspace and +dependencies. Using the `uv` project interface, all of the workspace packages are locked together. +`uv run` installs only the current package (unless overridden with `--package`) and its workspace and non-workspace dependencies. ## Configuration -You can create a workspace by adding a `tool.uv.workspace` to a pyproject.toml that is the workspace +A workspace can be created by adding a `tool.uv.workspace` to a pyproject.toml that is the workspace root. This table contains `members` (mandatory) and `exclude` (optional), with lists of globs of directories: @@ -21,7 +22,7 @@ members = ["packages/*", "examples/*"] exclude = ["example/excluded_example"] ``` -If you define `tool.uv.sources` in your workspace root, it applies to all packages, unless +If `tool.uv.sources` is defined in the workspace root, it applies to all packages, unless overridden in the `tool.uv.sources` of a specific project. ## Common usage diff --git a/docs/python.md b/docs/python.md new file mode 100644 index 000000000000..ffdbbabeaf2d --- /dev/null +++ b/docs/python.md @@ -0,0 +1 @@ +# Python environments diff --git a/docs/python/discovery.md b/docs/python/discovery.md new file mode 100644 index 000000000000..c0a7d0710ab5 --- /dev/null +++ b/docs/python/discovery.md @@ -0,0 +1,45 @@ +# Python discovery + +uv itself does not depend on Python, but it does need to locate a Python environment to (1) +install dependencies into the environment and (2) build source distributions. + +## Environment mutating commands + +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. + +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. + +## Commands that need an interpreter + +When running a command that needs an interpreter but does not mutate the environment such as `uv pip compile`, +uv does not _require_ a virtual environment and will search for a Python interpreter in the following order: + +- An activated virtual environment based on the `VIRTUAL_ENV` environment variable. +- An activated Conda environment based on the `CONDA_PREFIX` environment variable. +- A virtual environment at `.venv` in the current directory, or in the nearest parent directory. +- The Python interpreter available as `python3` on macOS and Linux, or `python.exe` on Windows. + +If a `--python-version` is provided to `uv 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. + +These commands may create ephemeral virtual environments with the interpreter. diff --git a/docs/resolution.md b/docs/resolution.md new file mode 100644 index 000000000000..385d3fb6431c --- /dev/null +++ b/docs/resolution.md @@ -0,0 +1,144 @@ +# Resolution + +## Resolution strategy + +By default, uv follows the standard Python dependency resolution strategy of preferring the +latest compatible version of each package. For example, `uv pip install flask>=2.0.0` will +install the latest version of Flask (at time of writing: `3.0.0`). + +However, uv's resolution strategy can be configured to support alternative workflows. With +`--resolution=lowest`, uv will install the **lowest** compatible versions for all dependencies, +both **direct** and **transitive**. Alternatively, `--resolution=lowest-direct` will opt for the +**lowest** compatible versions for all **direct** dependencies, while using the **latest** +compatible versions for all **transitive** dependencies. This distinction can be particularly useful +for library authors who wish to test against the lowest supported versions of direct dependencies +without restricting the versions of transitive dependencies. + +For example, given the following `requirements.in` file: + +```text +flask>=2.0.0 +``` + +Running `uv pip compile requirements.in` would produce the following `requirements.txt` file: + +```text +# This file was autogenerated by uv via the following command: +# uv pip compile requirements.in +blinker==1.7.0 + # via flask +click==8.1.7 + # via flask +flask==3.0.0 +itsdangerous==2.1.2 + # via flask +jinja2==3.1.2 + # via flask +markupsafe==2.1.3 + # via + # jinja2 + # werkzeug +werkzeug==3.0.1 + # via flask +``` + +However, `uv pip compile --resolution=lowest requirements.in` would instead produce: + +```text +# This file was autogenerated by uv via the following command: +# uv pip compile requirements.in --resolution=lowest +click==7.1.2 + # via flask +flask==2.0.0 +itsdangerous==2.0.0 + # via flask +jinja2==3.0.0 + # via flask +markupsafe==2.0.0 + # via jinja2 +werkzeug==2.0.0 + # via flask +``` + +## Pre-release handling + +By default, uv will accept pre-release versions during dependency resolution in two cases: + +1. If the package is a direct dependency, and its version markers include a pre-release specifier + (e.g., `flask>=2.0.0rc1`). +1. If _all_ published versions of a package are pre-releases. + +If dependency resolution fails due to a transitive pre-release, uv will prompt the user to +re-run with `--prerelease=allow`, to allow pre-releases for all dependencies. + +Alternatively, you can add the transitive dependency to your `requirements.in` file with a +pre-release specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific +dependency. + +Pre-releases are [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) +to model, and are a frequent source of bugs in other packaging tools. uv's pre-release handling +is _intentionally_ limited and _intentionally_ requires user opt-in for pre-releases, to ensure +correctness. + +For more, see ["Pre-release compatibility"](./PIP_COMPATIBILITY.md#pre-release-compatibility) + +## Dependency overrides + +Historically, `pip` has supported "constraints" (`-c constraints.txt`), which allows users to +narrow the set of acceptable versions for a given package. + +uv supports constraints, but also takes this concept further by allowing users to _override_ the +acceptable versions of a package across the dependency tree via overrides (`--override overrides.txt`). + +In short, overrides allow the user to lie to the resolver by overriding the declared dependencies +of a package. Overrides are a useful last resort for cases in which the user knows that a +dependency is compatible with a newer version of a package than the package declares, but the +package has not yet been updated to declare that compatibility. + +For example, if a transitive dependency declares `pydantic>=1.0,<2.0`, but the user knows that +the package is compatible with `pydantic>=2.0`, the user can override the declared dependency +with `pydantic>=2.0,<3` to allow the resolver to continue. + +While constraints are purely _additive_, and thus cannot _expand_ the set of acceptable versions for +a package, overrides _can_ expand the set of acceptable versions for a package, providing an escape +hatch for erroneous upper version bounds. + +## Multi-platform resolution + +By default, uv's `pip-compile` command produces a resolution that's known to be compatible with +the current platform and Python version. Unlike Poetry and PDM, uv does not yet produce a +machine-agnostic lockfile ([#2679](https://github.com/astral-sh/uv/issues/2679)). + +However, uv _does_ support resolving for alternate platforms and Python versions via the +`--python-platform` and `--python-version` command line arguments. + +For example, if you're running uv on macOS, but want to resolve for Linux, you can run +`uv pip compile --python-platform=linux requirements.in` to produce a `manylinux2014`-compatible +resolution. + +Similarly, if you're running uv on Python 3.9, but want to resolve for Python 3.8, you can run +`uv pip compile --python-version=3.8 requirements.in` to produce a Python 3.8-compatible resolution. + +The `--python-platform` and `--python-version` arguments can be combined to produce a resolution for +a specific platform and Python version, enabling users to generate multiple lockfiles for +different environments from a single machine. + +_N.B. Python's environment markers expose far more information about the current machine +than can be expressed by a simple `--python-platform` argument. For example, the `platform_version` marker +on macOS includes the time at which the kernel was built, which can (in theory) be encoded in +package requirements. uv's resolver makes a best-effort attempt to generate a resolution that is +compatible with any machine running on the target `--python-platform`, which should be sufficient for +most use cases, but may lose fidelity for complex package and platform combinations._ + +## Time-restricted reproducible resolutions + +uv supports an `--exclude-newer` option to limit resolution to distributions published before a specific +date, allowing reproduction of installations regardless of new package releases. The date may be specified +as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamp (e.g., `2006-12-02T02:07:43Z`) or +UTC date in the same format (e.g., `2006-12-02`). + +Note the package index must support the `upload-time` field as specified in [`PEP 700`](https://peps.python.org/pep-0700/). +If the field is not present for a given distribution, the distribution will be treated as unavailable. + +To ensure reproducibility, messages for unsatisfiable resolutions will not mention that distributions were excluded +due to the `--exclude-newer` flag โ€” newer distributions will be treated as if they do not exist. diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 000000000000..9834d4d44bb7 --- /dev/null +++ b/docs/style.css @@ -0,0 +1,42 @@ +/* Improve the font rendering */ +html { + font-family: -apple-system, BlinkMacSystemFont, Inter, Segoe UI, Helvetica Neue, sans-serif; +} +.heading, a, code, kbd, li, p, span, td { + -webkit-font-smoothing: antialiased; +} + +/* Improve padding and display of the navbar */ +.chapter { + padding-inline-start: 1.2rem; +} +.chapter li.chapter-item { + margin-left: 1em; + margin-block-start: 0.3em; + font-weight: 300; + margin-block-end: 0.5em +} +.chapter li.chapter-item a:hover { + text-decoration: underline; +} +.chapter li.part-title { + margin: 10px 0 0px 0; + font-weight: 500; + font-size: 1.3em; +} + +/* Special case the landing page in the navbar */ +.chapter li.chapter-item:first-child { + margin-left: 0; + font-size: 16px +} + +/* Hide the global title, it doesn't look good */ +.menu-title { + visibility: hidden; +} + +/* Reduce spacing between sections in content */ +h2, h3 { + margin-block-start: 1.2em; +} diff --git a/docs/theme/favicon.ico b/docs/theme/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..b247f569ffc8e1f773f8edf295ed0987855813a8 GIT binary patch literal 4286 zcmeI0?@Lor7{_maflermum)Qq>FyTphcgO$QAtH=FA8V4EqbBmFU-v!+fp~z5Bg#6 zf+#3SQYnji*}sv{i%dmmZrTr<+RJa}Id)-fcOrPU5p>4)o^cO%pXYhbbI!TXBxx7> zXtfeurHOn=+9OF)DHFRTRWs3j-q@H<-qhv|Ny48N{~5>BlW{a0uZN|u45oq-p)wa9 z!iA&fF#hlcl zZ%a!}vxqc(VsRQ2%3pHMrto9VIgpZVTX8M$c_Q0I_}?S9rZ9*(-#CN0#t$iDG*6Tx zqWB(TDxVmSj*a3$RTweX-!Y&u%1?3pt0_KGjPF(kF<8;Vb24!bHu-*Ge6LZRKWZPr zP=!~OPwP^Y|6XI8s{f-b_UZUxt4|oe*VL}gXZ{bHdsY1pTLy&j`_l05vppu5hCd>Z z-*4(r^`G{*khxFQ|B$6$nE%A5{U>n`Qu3cTl<&#;Pj-pOKRQEB7gwX((9F*u+KWjZ zwkFPNYf#6|n_go(QyXZW$kqWsg)zL-YkJ~^u~pgN0upL{%yU+WtPcKLY>vQd8#L(bE)db0;q z^HTe^{1u_D0FMK&KQmDWYD&0|RO|U$yog1joUL3oSRCF>yyp2(#d1>g+Oe}bi)y{; Ru_>&vnpbJc{{Xq_e*^Vi0M!5h literal 0 HcmV?d00001 diff --git a/docs/theme/favicon.svg b/docs/theme/favicon.svg new file mode 100644 index 000000000000..1701389d6747 --- /dev/null +++ b/docs/theme/favicon.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docs/versioning.md b/docs/versioning.md new file mode 100644 index 000000000000..300605960210 --- /dev/null +++ b/docs/versioning.md @@ -0,0 +1,9 @@ +# Versioning + +uv uses a custom versioning scheme in which the minor version number is bumped for breaking changes, +and the patch version number is bumped for bug fixes, enhancements, and other non-breaking changes. + +uv does not yet have a stable API; once uv's API is stable (v1.0.0), the versioning scheme will +adhere to [Semantic Versioning](https://semver.org/). + +uv's changelog can be [viewed on GitHub](https://github.com/astral-sh/uv/blob/main/CHANGELOG.md).