mirrors/uv
1
0
Fork 0
mirror of https://github.com/astral-sh/uv.git synced 2025-09-27 20:49:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Wrap documentation at 100 characters (#5635)

Browse source 
Basically sick of dealing with mixed formatting here. Going with the
number at
7c08e61b73/.editorconfig (L20)
This commit is contained in:
Zanie Blue 2024-07-30 18:17:58 -04:00 • committed by GitHub
parent b081425a77
commit f971631adf
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
34 changed files with 791 additions and 505 deletions
Download patch file Download diff file Expand all files Collapse all files

56
CONTRIBUTING.md
View file

@ -1,6 +1,10 @@
# Contributing # Contributing
We have issues labeled as [Good First Issue](https://github.com/astral-sh/uv/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) and [Help Wanted](https://github.com/astral-sh/uv/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) which are good opportunities for new contributors. We have issues labeled as [Good First
Issue](https://github.com/astral-sh/uv/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
and [Help
Wanted](https://github.com/astral-sh/uv/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
which are good opportunities for new contributors.
## Setup ## Setup
@ -26,7 +30,8 @@ See the [Python](#python) section for instructions on installing the Python vers
### Windows ### Windows
You can install CMake from the [installers](https://cmake.org/download/) or with `pipx install cmake`. You can install CMake from the [installers](https://cmake.org/download/) or with `pipx install
cmake`.
## Testing ## Testing
@ -55,10 +60,11 @@ cargo run -- pip install requests
### Testing on Windows ### Testing on Windows
When testing debug builds on Windows, the stack can overflow resulting in a `STATUS_STACK_OVERFLOW` error code. When testing debug builds on Windows, the stack can overflow resulting in a `STATUS_STACK_OVERFLOW`
This is due to a small stack size limit on Windows that we encounter when running unoptimized builds — the release error code. This is due to a small stack size limit on Windows that we encounter when running
builds do not have this problem. We [added a `UV_STACK_SIZE` variable](https://github.com/astral-sh/uv/pull/941) to unoptimized builds — the release builds do not have this problem. We [added a `UV_STACK_SIZE`
bypass this problem during testing. We recommend bumping the stack size from the default of 1MB to 2MB, for example: variable](https://github.com/astral-sh/uv/pull/941) to bypass this problem during testing. We
recommend bumping the stack size from the default of 1MB to 2MB, for example:
```powershell ```powershell
$Env:UV_STACK_SIZE = '2000000' $Env:UV_STACK_SIZE = '2000000'
@ -66,7 +72,11 @@ $Env:UV_STACK_SIZE = '2000000'
## Running inside a Docker container ## Running inside a Docker container
Source distributions can run arbitrary code on build and can make unwanted modifications to your system (["Someone's Been Messing With My Subnormals!" on Blogspot](https://moyix.blogspot.com/2022/09/someones-been-messing-with-my-subnormals.html), ["nvidia-pyindex" on PyPI](https://pypi.org/project/nvidia-pyindex/)), which can even occur when just resolving requirements. To prevent this, there's a Docker container you can run commands in: Source distributions can run arbitrary code on build and can make unwanted modifications to your
system (["Someone's Been Messing With My Subnormals!" on
Blogspot](https://moyix.blogspot.com/2022/09/someones-been-messing-with-my-subnormals.html),
["nvidia-pyindex" on PyPI](https://pypi.org/project/nvidia-pyindex/)), which can even occur when
just resolving requirements. To prevent this, there's a Docker container you can run commands in:
```bash ```bash
docker buildx build -t uv-builder -f builder.dockerfile --load . docker buildx build -t uv-builder -f builder.dockerfile --load .
@ -75,15 +85,20 @@ cargo build --target x86_64-unknown-linux-musl --profile profiling
docker run --rm -it -v $(pwd):/app uv-builder /app/target/x86_64-unknown-linux-musl/profiling/uv-dev resolve-many --cache-dir /app/cache-docker /app/scripts/popular_packages/pypi_10k_most_dependents.txt docker run --rm -it -v $(pwd):/app uv-builder /app/target/x86_64-unknown-linux-musl/profiling/uv-dev resolve-many --cache-dir /app/cache-docker /app/scripts/popular_packages/pypi_10k_most_dependents.txt
``` ```
We recommend using this container if you don't trust the dependency tree of the package(s) you are trying to resolve or install. We recommend using this container if you don't trust the dependency tree of the package(s) you are
trying to resolve or install.
## Profiling and Benchmarking ## Profiling and Benchmarking
Please refer to Ruff's [Profiling Guide](https://github.com/astral-sh/ruff/blob/main/CONTRIBUTING.md#profiling-projects), it applies to uv, too. Please refer to Ruff's [Profiling
Guide](https://github.com/astral-sh/ruff/blob/main/CONTRIBUTING.md#profiling-projects), it applies
to uv, too.
We provide diverse sets of requirements for testing and benchmarking the resolver in `scripts/requirements` and for the installer in `scripts/requirements/compiled`. We provide diverse sets of requirements for testing and benchmarking the resolver in
`scripts/requirements` and for the installer in `scripts/requirements/compiled`.
You can use `scripts/benchmark` to benchmark predefined workloads between uv versions and with other tools, e.g., from the `scripts/benchmark` directory: You can use `scripts/benchmark` to benchmark predefined workloads between uv versions and with other
tools, e.g., from the `scripts/benchmark` directory:
```shell ```shell
uv run resolver \ uv run resolver \
@ -96,7 +111,9 @@ uv run resolver \
### Analyzing concurrency ### Analyzing concurrency
You can use [tracing-durations-export](https://github.com/konstin/tracing-durations-export) to visualize parallel requests and find any spots where uv is CPU-bound. Example usage, with `uv` and `uv-dev` respectively: You can use [tracing-durations-export](https://github.com/konstin/tracing-durations-export) to
visualize parallel requests and find any spots where uv is CPU-bound. Example usage, with `uv` and
`uv-dev` respectively:
```shell ```shell
RUST_LOG=uv=info TRACING_DURATIONS_FILE=target/traces/jupyter.ndjson cargo run --features tracing-durations-export --profile profiling -- pip compile scripts/requirements/jupyter.in RUST_LOG=uv=info TRACING_DURATIONS_FILE=target/traces/jupyter.ndjson cargo run --features tracing-durations-export --profile profiling -- pip compile scripts/requirements/jupyter.in
@ -157,15 +174,17 @@ To preview any changes to the documentation locally:
The documentation should then be available locally at The documentation should then be available locally at
[http://127.0.0.1:8000/uv/](http://127.0.0.1:8000/uv/). [http://127.0.0.1:8000/uv/](http://127.0.0.1:8000/uv/).
To update the documentation dependencies, edit `docs/requirements.in` and `docs/requirements-insiders.in`, then run: To update the documentation dependencies, edit `docs/requirements.in` and
`docs/requirements-insiders.in`, then run:
```shell ```shell
uv pip compile docs/requirements.in -o docs/requirements.txt --universal -p 3.12 uv pip compile docs/requirements.in -o docs/requirements.txt --universal -p 3.12
uv pip compile docs/requirements-insiders.in -o docs/requirements-insiders.txt --universal -p 3.12 uv pip compile docs/requirements-insiders.in -o docs/requirements-insiders.txt --universal -p 3.12
``` ```
Documentation is deployed automatically on release by publishing to the [Astral documentation](https://github.com/astral-sh/docs) Documentation is deployed automatically on release by publishing to the [Astral
repository, which itself deploys via Cloudflare Pages. documentation](https://github.com/astral-sh/docs) repository, which itself deploys via Cloudflare
Pages.
## Releases ## Releases
@ -183,6 +202,7 @@ Then, open a pull request e.g. `Bump version to ...`.
Binary builds will automatically be tested for the release. Binary builds will automatically be tested for the release.
After merging the pull request, run the [release workflow](https://github.com/astral-sh/uv/actions/workflows/release.yml) After merging the pull request, run the [release
with the version tag. **Do not include a leading `v`**. workflow](https://github.com/astral-sh/uv/actions/workflows/release.yml) with the version tag. **Do
The release will automatically be created on GitHub after everything else publishes. not include a leading `v`**. The release will automatically be created on GitHub after everything
else publishes.

16
STYLE.md
View file

@ -1,6 +1,7 @@
# Style guide # Style guide
_The following is a work-in-progress style guide for our user-facing messaging in the CLI output and documentation_. _The following is a work-in-progress style guide for our user-facing messaging in the CLI output and
documentation_.
## General ## General
@ -9,9 +10,12 @@ _The following is a work-in-progress style guide for our user-facing messaging i
1. Always wrap em-dashes in spaces, e.g., "hello — world" not "hello—world". 1. Always wrap em-dashes in spaces, e.g., "hello — world" not "hello—world".
1. Hyphenate compound words, e.g., use "platform-specific" not "platform specific". 1. Hyphenate compound words, e.g., use "platform-specific" not "platform specific".
1. Use backticks to escape: commands, code expressions, package names, and file paths. 1. Use backticks to escape: commands, code expressions, package names, and file paths.
1. Use less than and greater than symbols to wrap bare URLs, e.g., `<https://astral.sh>` (unless it is an example; then, use backticks). 1. Use less than and greater than symbols to wrap bare URLs, e.g., `<https://astral.sh>` (unless it
is an example; then, use backticks).
1. Avoid bare URLs outside of reference documentation, prefer labels, e.g., `[name](url)`. 1. Avoid bare URLs outside of reference documentation, prefer labels, e.g., `[name](url)`.
1. If a message ends with a single relevant value, precede it with a colon, e.g., `This is the value: value`. If the value is a literal, wrap it in backticks. 1. If a message ends with a single relevant value, precede it with a colon, e.g., `This is the
value: value`. If the value is a literal, wrap it in backticks.
1. Markdown files should be wrapped at 100 characters
## Styling uv ## Styling uv
@ -82,12 +86,14 @@ The documentation is divided into:
## CLI ## CLI
1. Do not use periods at the end of sentences :), unless the message spans more than a single sentence. 1. Do not use periods at the end of sentences :), unless the message spans more than a single
sentence.
1. May use the second-person point of view, e.g., "Did you mean...?". 1. May use the second-person point of view, e.g., "Did you mean...?".
### Colors and style ### Colors and style
1. All CLI output must be interpretable and understandable _without_ the use of color and other styling. (For example: even if a command is rendered in green, wrap it in backticks.) 1. All CLI output must be interpretable and understandable _without_ the use of color and other
styling. (For example: even if a command is rendered in green, wrap it in backticks.)
1. `NO_COLOR` must be respected when using any colors or styling. 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. `UV_NO_PROGRESS` must be respected when using progress-styling like bars or spinners.
1. In general, use: 1. In general, use:

63
docs/concepts/cache.md
View file

@ -2,33 +2,34 @@
## Dependency caching ## Dependency caching
uv uses aggressive caching to avoid re-downloading (and re-building dependencies) that have uv uses aggressive caching to avoid re-downloading (and re-building dependencies) that have already
already been accessed in prior runs. been accessed in prior runs.
The specifics of uv's caching semantics vary based on the nature of the dependency: 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 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 - **For direct URL dependencies**, uv respects HTTP caching headers, and also caches based on the
the URL itself. URL itself.
- **For Git dependencies**, uv caches based on the fully-resolved Git commit hash. As such, - **For Git dependencies**, uv caches based on the fully-resolved Git commit hash. As such, `uv pip
`uv pip compile` will pin Git dependencies to a specific commit hash when writing the resolved compile` will pin Git dependencies to a specific commit hash when writing the resolved dependency
dependency set. set.
- **For local dependencies**, uv caches based on the last-modified time of the source archive (i.e., - **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 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. the `pyproject.toml`, `setup.py`, or `setup.cfg` file.
It's safe to run multiple uv commands concurrently, even against the same virtual environment. It's safe to run multiple uv commands concurrently, even against the same virtual environment. uv's
uv's cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent readers
readers and writers. uv applies a file-based lock to the target virtual environment when installing, and writers. uv applies a file-based lock to the target virtual environment when installing, to
to avoid concurrent modifications across processes. avoid concurrent modifications across processes.
Note that it's _not_ safe to modify the uv cache (e.g., `uv cache clean`) while other uv commands are Note that it's _not_ safe to modify the uv cache (e.g., `uv cache clean`) while other uv commands
running, and _never_ safe to modify the cache directly (e.g., by removing a file or directory). 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: 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 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 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 ignore existing installed versions, run `uv pip install --reinstall ...`.
## Clearing the cache ## Clearing the cache
@ -36,25 +37,27 @@ If you're running into caching issues, uv includes a few escape hatches:
uv provides a few different mechanisms for removing entries from 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` 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 - `uv cache clean ruff` removes all cache entries for the `ruff` package, useful for invalidating
single or finite set of packages. 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 - `uv cache prune` removes all _unused_ cache entries. For example, the cache directory may contain
previous uv versions that are no longer necessary and can be safely removed. `uv cache prune` is safe to entries created in previous uv versions that are no longer necessary and can be safely removed.
run periodically, to keep the cache directory clean. `uv cache prune` is safe to run periodically, to keep the cache directory clean.
## Caching in continuous integration ## Caching in continuous integration
It's common to cache package installation artifacts in continuous integration environments (like GitHub Actions or It's common to cache package installation artifacts in continuous integration environments (like
GitLab CI) to speed up subsequent runs. GitHub Actions or GitLab CI) to speed up subsequent runs.
By default, uv caches both the wheels that it builds from source and the pre-built wheels that it downloads directly, By default, uv caches both the wheels that it builds from source and the pre-built wheels that it
to enable high-performance package installation. downloads directly, to enable high-performance package installation.
However, in continuous integration environments, persisting pre-built wheels may be undesirable. With uv, it turns out However, in continuous integration environments, persisting pre-built wheels may be undesirable.
that it's often faster to _omit_ pre-built wheels from the cache (and instead re-download them from the registry on each With uv, it turns out that it's often faster to _omit_ pre-built wheels from the cache (and instead
run). On the other hand, caching wheels that are built from source tends to be worthwhile, since the wheel building re-download them from the registry on each run). On the other hand, caching wheels that are built
process can be expensive, especially for extension modules. from source tends to be worthwhile, since the wheel building process can be expensive, especially
for extension modules.
To support this caching strategy, uv provides a `uv cache prune --ci` command, which removes all pre-built wheels from To support this caching strategy, uv provides a `uv cache prune --ci` command, which removes all
the cache but retains any wheels that were built from source. We recommend running `uv cache prune --ci` at the end of pre-built wheels from the cache but retains any wheels that were built from source. We recommend
your continuous integration job to ensure maximum cache efficiency. running `uv cache prune --ci` at the end of your continuous integration job to ensure maximum cache
efficiency.

99
docs/concepts/dependencies.md
View file

@ -1,23 +1,26 @@
# Specifying dependencies # Specifying dependencies
In uv, project dependency specification is divided between two `pyproject.toml` tables: `project.dependencies` and In uv, project dependency specification is divided between two `pyproject.toml` tables:
`tool.uv.sources`. `project.dependencies` and `tool.uv.sources`.
`project.dependencies` is used to define the standards-compliant dependency metadata, `project.dependencies` is used to define the standards-compliant dependency metadata, propagated
propagated when uploading to PyPI or building a wheel. `tool.uv.sources` is used to specify the _sources_ when uploading to PyPI or building a wheel. `tool.uv.sources` is used to specify the _sources_
required to install the dependencies, which can come from a Git repository, a URL, a local path, a required to install the dependencies, which can come from a Git repository, a URL, a local path, a
different index, etc. This metadata must be expressed separately because the `project.dependencies` standard does not allow these common patterns. different index, etc. This metadata must be expressed separately because the `project.dependencies`
standard does not allow these common patterns.
## Project dependencies ## Project dependencies
The `project.dependencies` table represents the dependencies that are used when uploading to PyPI or The `project.dependencies` table represents the dependencies that are used when uploading to PyPI or
building a wheel. Individual dependencies are specified using [PEP 508](#pep-508) syntax, and the table follows the [PEP 621](https://packaging.python.org/en/latest/specifications/pyproject-toml/) building a wheel. Individual dependencies are specified using [PEP 508](#pep-508) syntax, and the
table follows the [PEP 621](https://packaging.python.org/en/latest/specifications/pyproject-toml/)
standard. standard.
`project.dependencies` defines the packages that are required for the project, along with the version constraints that should be used when installing them. `project.dependencies` defines the packages that are required for the project, along with the
version constraints that should be used when installing them.
`project.dependencies` is structured as a list. Each entry includes a dependency name and `project.dependencies` is structured as a list. Each entry includes a dependency name and version.
version. An entry may include extras or environment markers for platform-specific packages. For example: An entry may include extras or environment markers for platform-specific packages. For example:
```toml title="pyproject.toml" ```toml title="pyproject.toml"
[project] [project]
@ -37,11 +40,14 @@ dependencies = [
] ]
``` ```
If the project only requires packages from standard package indexes, then `project.dependencies` is sufficient. If, the project depends on packages from Git, remote URLs, or local sources, `tool.uv.sources` is needed. If the project only requires packages from standard package indexes, then `project.dependencies` is
sufficient. If, the project depends on packages from Git, remote URLs, or local sources,
`tool.uv.sources` is needed.
## Dependency sources ## Dependency sources
During development, the project may rely on a package that isn't available on PyPI. The following additional sources are supported by uv: During development, the project may rely on a package that isn't available on PyPI. The following
additional sources are supported by uv:
- Git - Git
- URL - URL
@ -51,8 +57,8 @@ During development, the project may rely on a package that isn't available on Py
Only a single source may be defined for each dependency. Only a single source may be defined for each dependency.
Note that if a non-uv project uses a project with sources as a Git- or path-dependency, only Note that if a non-uv project uses a project with sources as a Git- or path-dependency, only
`project.dependencies` is respected, the information in the source table `project.dependencies` is respected, the information in the source table will need to be
will need to be re-specified in a format specific to the other package manager. re-specified in a format specific to the other package manager.
### Git ### Git
@ -84,11 +90,14 @@ $ uv add git+https://github.com/encode/httpx --branch main
$ uv add git+https://github.com/encode/httpx --rev 326b943 $ uv add git+https://github.com/encode/httpx --rev 326b943
``` ```
Git dependencies can also be manually added or edited in the `pyproject.toml` with the `{ git = <url> }` syntax. A target revision may be specified with one of: `rev`, `tag`, or `branch`. A `subdirectory` may be specified if the package isn't in the repository root. Git dependencies can also be manually added or edited in the `pyproject.toml` with the `{ git =
<url> }` syntax. A target revision may be specified with one of: `rev`, `tag`, or `branch`. A
`subdirectory` may be specified if the package isn't in the repository root.
### URL ### URL
To add a URL source, provide a `https://` URL to either a wheel (ending in `.whl`) or a source distribution (ending in `.zip` or `.tar.gz`). To add a URL source, provide a `https://` URL to either a wheel (ending in `.whl`) or a source
distribution (ending in `.zip` or `.tar.gz`).
For example: For example:
@ -108,11 +117,14 @@ dependencies = [
httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz" } httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz" }
``` ```
URL dependencies can also be manually added or edited in the `pyproject.toml` with the `{ url = <url> }` syntax. A `subdirectory` may be specified if the if the source distribution isn't in the archive root. URL dependencies can also be manually added or edited in the `pyproject.toml` with the `{ url =
<url> }` syntax. A `subdirectory` may be specified if the if the source distribution isn't in the
archive root.
### Path ### Path
To add a path source, provide the path of a wheel (ending in `.whl`), a source distribution (ending in `.zip` or `.tar.gz`), or a directory containing a `pyproject.toml`. To add a path source, provide the path of a wheel (ending in `.whl`), a source distribution (ending
in `.zip` or `.tar.gz`), or a directory containing a `pyproject.toml`.
For example: For example:
@ -138,7 +150,8 @@ The path may also be a relative path, e.g.:
$ uv add ./foo $ uv add ./foo
``` ```
Note an [editable installation](#editables-dependencies) is not used for path dependencies. However, for directories, an editable installation may be requested, e.g.: Note an [editable installation](#editables-dependencies) is not used for path dependencies. However,
for directories, an editable installation may be requested, e.g.:
```console ```console
$ uv add --editable ./foo $ uv add --editable ./foo
@ -148,7 +161,10 @@ However, it is recommended to use [_workspaces_](#workspaces) instead of manual
### Workspace member ### Workspace member
To declare a workspace member, add the dependency with `{ workspace = true }`. All workspace members must be explicitly stated. Workspace members are [editable](#editables-dependencies) by default; `editable = false` may be included to install them as regular dependencies. See the [workspace](./workspaces.md) documentation for more details on workspaces. To declare a workspace member, add the dependency with `{ workspace = true }`. All workspace members
must be explicitly stated. Workspace members are [editable](#editables-dependencies) by default;
`editable = false` may be included to install them as regular dependencies. See the
[workspace](./workspaces.md) documentation for more details on workspaces.
```toml title="pyproject.toml" ```toml title="pyproject.toml"
[project] [project]
@ -167,9 +183,12 @@ include = [
## Optional dependencies ## Optional dependencies
It is common for projects that are published as libraries to make some features optional to reduce the default dependency tree. For example, It is common for projects that are published as libraries to make some features optional to reduce
Pandas has an [`excel` extra](https://pandas.pydata.org/docs/getting_started/install.html#excel-files) the default dependency tree. For example, Pandas has an [`excel`
and a [`plot` extra](https://pandas.pydata.org/docs/getting_started/install.html#visualization) to avoid installation of Excel parsers and `matplotlib` unless someone explicitly requires them. Extras are requested with the `package[<extra>]` syntax, e.g., `pandas[plot, excel]`. extra](https://pandas.pydata.org/docs/getting_started/install.html#excel-files) and a [`plot`
extra](https://pandas.pydata.org/docs/getting_started/install.html#visualization) to avoid
installation of Excel parsers and `matplotlib` unless someone explicitly requires them. Extras are
requested with the `package[<extra>]` syntax, e.g., `pandas[plot, excel]`.
Optional dependencies are specified in `[project.optional-dependencies]`, a TOML table that maps Optional dependencies are specified in `[project.optional-dependencies]`, a TOML table that maps
from extra name to its dependencies, following [PEP 508](#pep-508) syntax. from extra name to its dependencies, following [PEP 508](#pep-508) syntax.
@ -203,7 +222,9 @@ $ uv add httpx --optional network
## Development dependencies ## Development dependencies
Unlike optional dependencies, development dependencies are local-only and will _not_ be included in the project requirements when published to PyPI or other indexes. As such, development dependencies are included under `[tool.uv]` instead of `[project]`. Unlike optional dependencies, development dependencies are local-only and will _not_ be included in
the project requirements when published to PyPI or other indexes. As such, development dependencies
are included under `[tool.uv]` instead of `[project]`.
Development dependencies can have entries in `tool.uv.sources` the same as normal dependencies. Development dependencies can have entries in `tool.uv.sources` the same as normal dependencies.
@ -222,7 +243,8 @@ $ uv add ruff --dev`
## PEP 508 ## PEP 508
[PEP 508](https://peps.python.org/pep-0508/) defines a syntax for dependency specification. It is composed of, in order: [PEP 508](https://peps.python.org/pep-0508/) defines a syntax for dependency specification. It is
composed of, in order:
- The dependency name - The dependency name
- The extras you want (optional) - The extras you want (optional)
@ -238,30 +260,31 @@ A star can be used for the last digit with equals, e.g. `foo ==2.1.*` will accep
the 2.1 series. Similarly, `~=` matches where the last digit is equal or higher, e.g., `foo ~=1.2` the 2.1 series. Similarly, `~=` matches where the last digit is equal or higher, e.g., `foo ~=1.2`
is equal to `foo >=1.2,<2`, and `foo ~=1.2.3` is equal to `foo >=1.2.3,<1.3`. is equal to `foo >=1.2,<2`, and `foo ~=1.2.3` is equal to `foo >=1.2.3,<1.3`.
Extras are comma-separated in square bracket between name and version, e.g., `pandas[excel,plot] ==2.2`. Whitespace between extra names is ignored. Extras are comma-separated in square bracket between name and version, e.g., `pandas[excel,plot]
==2.2`. Whitespace between extra names is ignored.
Some dependencies are only required in specific environments, e.g., a specific Python version or Some dependencies are only required in specific environments, e.g., a specific Python version or
operating system. For example to install the `importlib-metadata` backport for the operating system. For example to install the `importlib-metadata` backport for the
`importlib.metadata` module, use `importlib-metadata >=7.1.0,<8; python_version < '3.10'`. `importlib.metadata` module, use `importlib-metadata >=7.1.0,<8; python_version < '3.10'`. To
To install `colorama` on Windows (but omit it on other platforms), use install `colorama` on Windows (but omit it on other platforms), use `colorama >=0.4.6,<5;
`colorama >=0.4.6,<5; platform_system == "Windows"`. platform_system == "Windows"`.
Markers are combined with `and`, `or`, and parentheses, e.g., `aiohttp >=3.7.4,<4; (sys_platform != 'win32' or implementation_name != 'pypy') and python_version >= '3.10'`. Markers are combined with `and`, `or`, and parentheses, e.g., `aiohttp >=3.7.4,<4; (sys_platform !=
Note that versions within markers must be quoted, while versions _outside_ of markers must _not_ be 'win32' or implementation_name != 'pypy') and python_version >= '3.10'`. Note that versions within
quoted. markers must be quoted, while versions _outside_ of markers must _not_ be quoted.
## Editable dependencies ## Editable dependencies
A regular installation of a directory with a Python package first builds a wheel and then installs A regular installation of a directory with a Python package first builds a wheel and then installs
that wheel into your virtual environment, copying all source files. When the package source files are edited, that wheel into your virtual environment, copying all source files. When the package source files
the virtual environment will contain outdated versions. are edited, the virtual environment will contain outdated versions.
Editable installations solve this problem by adding a link to the project within the virtual environment Editable installations solve this problem by adding a link to the project within the virtual
(a `.pth` file), which instructs the interpreter to include the source files directly. environment (a `.pth` file), which instructs the interpreter to include the source files directly.
There are some limitations to editables (mainly: the build backend needs to support them, and There are some limitations to editables (mainly: the build backend needs to support them, and native
native modules aren't recompiled before import), but they are useful for development, as the modules aren't recompiled before import), but they are useful for development, as the virtual
virtual environment will always use the latest changes to the package. environment will always use the latest changes to the package.
uv uses editable installation for workspace packages by default. uv uses editable installation for workspace packages by default.

65
docs/concepts/projects.md
View file

@ -28,9 +28,12 @@ Additionally, it's recommended to include a Python version requirement:
requires-python = ">=3.12" requires-python = ">=3.12"
``` ```
This Python version requirement determines what syntax is valid in the project and affects the versions of dependencies which can be used (they must support the same Python range). This Python version requirement determines what syntax is valid in the project and affects the
versions of dependencies which can be used (they must support the same Python range).
The `pyproject.toml` also lists dependencies of the project. uv supports modifying the standard dependency list from the command line with `uv add` and `uv remove`. uv also supports [extended package sources](./dependencies.md) for advanced users. The `pyproject.toml` also lists dependencies of the project. uv supports modifying the standard
dependency list from the command line with `uv add` and `uv remove`. uv also supports [extended
package sources](./dependencies.md) for advanced users.
!!! tip !!! tip
@ -38,13 +41,23 @@ The `pyproject.toml` also lists dependencies of the project. uv supports modifyi
## Project environments ## Project environments
uv creates a virtual environment in a `.venv` directory next to the `pyproject.toml`. This virtual environment contains the project and its dependencies. It is stored inside the project to make it easy for editors to find — they need the environment to give code completions and type hints. It is not recommended to include the `.venv` directory in version control; it is automatically excluded from `git` with an internal `.gitignore` file. uv creates a virtual environment in a `.venv` directory next to the `pyproject.toml`. This virtual
environment contains the project and its dependencies. It is stored inside the project to make it
easy for editors to find — they need the environment to give code completions and type hints. It is
not recommended to include the `.venv` directory in version control; it is automatically excluded
from `git` with an internal `.gitignore` file.
To run a command in the project environment, use `uv run`. Alternatively the project environment can be activated as normal for a virtual environment. To run a command in the project environment, use `uv run`. Alternatively the project environment can
be activated as normal for a virtual environment.
When `uv run` is invoked, it will create the project environment if it does not exist yet or ensure it is up to date if it exists. The project environment can also be explicitly created with `uv sync`. When `uv run` is invoked, it will create the project environment if it does not exist yet or ensure
it is up to date if it exists. The project environment can also be explicitly created with `uv
sync`.
It is _not_ recommended to modify the project environment manually, e.g., with `uv pip install`. For project dependencies, use `uv add` to add a package to the environment. For one-off requirements, use [`uvx`](../guides/tools.md) or [`uv run --with`](#running-commands-with-additional-dependencies). It is _not_ recommended to modify the project environment manually, e.g., with `uv pip install`. For
project dependencies, use `uv add` to add a package to the environment. For one-off requirements,
use [`uvx`](../guides/tools.md) or [`uv run
--with`](#running-commands-with-additional-dependencies).
## Lockfile ## Lockfile
@ -62,14 +75,17 @@ A lockfile ensures that developers working on the project are using a consistent
versions. Additionally, it ensures when deploying the project as an application that the exact set versions. Additionally, it ensures when deploying the project as an application that the exact set
of used package versions is known. of used package versions is known.
The lockfile is created and updated during uv invocations that use the project environment, i.e., `uv sync` and `uv run`. The lockfile may also be explicitly updated using `uv lock`. The lockfile is created and updated during uv invocations that use the project environment, i.e.,
`uv sync` and `uv run`. The lockfile may also be explicitly updated using `uv lock`.
`uv.lock` is a human-readable TOML file but is managed by uv and should not be `uv.lock` is a human-readable TOML file but is managed by uv and should not be edited manually.
edited manually. There is no Python standard for lockfiles at this time, so the format of this file is specific to uv and not generally not usable by other tools. There is no Python standard for lockfiles at this time, so the format of this file is specific to uv
and not generally not usable by other tools.
To avoid updating the lockfile during `uv sync` and `uv run` invocations, use the `--frozen` flag. To avoid updating the lockfile during `uv sync` and `uv run` invocations, use the `--frozen` flag.
To assert the lockfile is up to date, use the `--locked` flag. If the lockfile is not up to date, an error will be raised instead of updating the lockfile. To assert the lockfile is up to date, use the `--locked` flag. If the lockfile is not up to date, an
error will be raised instead of updating the lockfile.
## Managing dependencies ## Managing dependencies
@ -81,7 +97,11 @@ To add a dependency:
$ uv add httpx $ uv add httpx
``` ```
uv supports adding [editable dependencies](./dependencies.md#editable-dependencies), [development dependencies](./dependencies.md#development-dependencies), [optional dependencies](./dependencies.md#optional-dependencies), and alternative [dependency sources](./dependencies.md#dependency-sources). See the [dependency specification](./dependencies.md) documentation for more details. uv supports adding [editable dependencies](./dependencies.md#editable-dependencies), [development
dependencies](./dependencies.md#development-dependencies), [optional
dependencies](./dependencies.md#optional-dependencies), and alternative [dependency
sources](./dependencies.md#dependency-sources). See the [dependency
specification](./dependencies.md) documentation for more details.
uv will raise an error if the dependency cannot be resolved, e.g.: uv will raise an error if the dependency cannot be resolved, e.g.:
@ -117,13 +137,16 @@ $ uv add git+https://github.com/encode/httpx
## Running commands ## Running commands
When working on a project, it is installed into virtual environment at `.venv`. This environment is isolated from the current shell by default, so invocations that require the project, e.g., `python -c "import example"`, will fail. Instead, use `uv run` to run commands in the project environment: When working on a project, it is installed into virtual environment at `.venv`. This environment is
isolated from the current shell by default, so invocations that require the project, e.g., `python
-c "import example"`, will fail. Instead, use `uv run` to run commands in the project environment:
```console ```console
$ uv run python -c "import example" $ uv run python -c "import example"
``` ```
When using `run`, uv will ensure that the project environment is up to date before running the given command. When using `run`, uv will ensure that the project environment is up to date before running the given
command.
The given command can be provided by the project environment or exist outside of it, e.g.: The given command can be provided by the project environment or exist outside of it, e.g.:
@ -139,7 +162,8 @@ $ uv run bash scripts/foo.sh
Additional dependencies or different versions of dependencies can be requested per invocation. Additional dependencies or different versions of dependencies can be requested per invocation.
The `--with` option is used to include a dependency for the invocation, e.g., to request a different version of `httpx`: The `--with` option is used to include a dependency for the invocation, e.g., to request a different
version of `httpx`:
```console ```console
$ uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)" $ uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)"
@ -148,11 +172,14 @@ $ uv run --with httpx==0.25.0 python -c "import httpx; print(httpx.__version__)"
0.25.0 0.25.0
``` ```
The requested version will be respected regardless of the project's requirements. For example, even if the project requires `httpx==0.24.0`, the output above would be the same. The requested version will be respected regardless of the project's requirements. For example, even
if the project requires `httpx==0.24.0`, the output above would be the same.
### Running scripts ### Running scripts
Scripts that declare inline metadata are automatically executed in environments isolated from the project. See the [scripts guide](../guides/scripts.md#declaring-script-dependencies) for more details. Scripts that declare inline metadata are automatically executed in environments isolated from the
project. See the [scripts guide](../guides/scripts.md#declaring-script-dependencies) for more
details.
For example, given a script: For example, given a script:
@ -170,8 +197,10 @@ data = resp.json()
print([(k, v["title"]) for k, v in data.items()][:10]) print([(k, v["title"]) for k, v in data.items()][:10])
``` ```
The invocation `uv run example.py` would run _isolated_ from the project with only the given dependencies listed. The invocation `uv run example.py` would run _isolated_ from the project with only the given
dependencies listed.
## Projects with many packages ## Projects with many packages
If working in a project composed of many packages, see the [workspaces](./workspaces.md) documentation. If working in a project composed of many packages, see the [workspaces](./workspaces.md)
documentation.

52
docs/concepts/python-versions.md
View file

@ -1,6 +1,8 @@
# Python versions # Python versions
A Python version 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 version installed. A Python version 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
version installed.
## Requesting a version ## Requesting a version
@ -12,7 +14,8 @@ For example, when creating a virtual environment:
uv venv --python 3.11.6 uv venv --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. uv will ensure that Python 3.11.6 is available — downloading and installing it if necessary — then
create the virtual environment with it.
Many Python version request formats are supported: Many Python version request formats are supported:
@ -56,15 +59,18 @@ uv python install 3.9 3.10 3.11
## Project Python versions ## Project Python versions
By default `uv python install` will verify that a managed Python version is installed or install the latest version. By default `uv python install` will verify that a managed Python version is installed or install the
latest version.
However, a project may define a `.python-version` file specifying the default Python version to be used. If present, However, a project may define a `.python-version` file specifying the default Python version to be
uv will install the Python version listed in the file. used. If present, uv will install the Python version listed in the file.
Alternatively, a project that requires multiple Python versions may also define a `.python-versions` file. If present, Alternatively, a project that requires multiple Python versions may also define a `.python-versions`
uv will install all of the Python versions listed in the file. This file takes precedence over the `.python-version` file. file. If present, uv will install all of the Python versions 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. uv will also respect Python requirements defined in a `pyproject.toml` file during project command
invocations.
## Viewing available Python versions ## Viewing available Python versions
@ -96,16 +102,20 @@ uv python list --only-installed
## Adjusting Python version preferences ## Adjusting Python version preferences
By default, uv will attempt to use Python versions found on the system and only download managed interpreters when necessary. By default, uv will attempt to use Python versions found on the system and only download managed
However, It's possible to adjust uv's Python version selection preference with the `python-preference` option. interpreters when necessary. However, It's possible to adjust uv's Python version selection
preference with the `python-preference` option.
- `only-managed`: Only use managed Python installations; never use system Python installations - `only-managed`: Only use managed Python installations; never use system Python installations
- `installed`: Prefer installed Python installations, only download managed Python installations if no system Python installation is found - `installed`: Prefer installed Python installations, only download managed Python installations
- `managed`: Prefer managed Python installations over system Python installations, even if fetching is required if no system Python installation is found
- `managed`: Prefer managed Python installations over system Python installations, even if
fetching is required
- `system`: Prefer system Python installations over managed Python installations - `system`: Prefer system Python installations over managed Python installations
- `only-system`: Only use system Python installations; never use 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. These options allow disabling uv's managed Python versions entirely or always using them and
ignoring any existing system installations.
## Discovery order ## Discovery order
@ -116,16 +126,24 @@ When searching for a Python version, the following locations are checked:
- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested - On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
version. version.
If a specific Python version is requested, e.g. `--python 3.7`, additional executable names are included in the search: If a specific Python version is requested, e.g. `--python 3.7`, additional executable names are
included in the search:
- A Python interpreter on the `PATH` as, e.g., `python3.7` on macOS and Linux. - A Python interpreter on the `PATH` as, e.g., `python3.7` on macOS and Linux.
## Python distributions ## Python distributions
Python does not publish official distributable CPython binaries, uv uses third-party standalone distributions from the [`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The project is partially maintained by the uv maintainers and is used by many other Python projects. Python does not publish official distributable CPython binaries, uv uses third-party standalone
distributions from the
[`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The
project is partially maintained by the uv maintainers and is used by many other Python projects.
The Python distributions are self-contained and highly-portable. Additionally, these distributions have various build-time optimizations enabled to ensure they are performant. The Python distributions are self-contained and highly-portable. Additionally, these distributions
have various build-time optimizations enabled to ensure they are performant.
These distributions have some behavior quirks, generally as a consequence of portability. See the [`python-build-standalone` quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) documentation for details. These distributions have some behavior quirks, generally as a consequence of portability. See the
[`python-build-standalone`
quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) documentation for
details.
PyPy distributions are provided by the PyPy project. PyPy distributions are provided by the PyPy project.

97
docs/concepts/resolution.md
View file

@ -2,13 +2,13 @@
## Resolution strategy ## Resolution strategy
By default, uv follows the standard Python dependency resolution strategy of preferring the By default, uv follows the standard Python dependency resolution strategy of preferring the latest
latest compatible version of each package. For example, `uv pip install flask>=2.0.0` will compatible version of each package. For example, `uv pip install flask>=2.0.0` will install the
install the latest version of Flask (at time of writing: `3.0.0`). latest version of Flask (at time of writing: `3.0.0`).
However, uv's resolution strategy can be configured to support alternative workflows. With 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, `--resolution=lowest`, uv will install the **lowest** compatible versions for all dependencies, both
both **direct** and **transitive**. Alternatively, `--resolution=lowest-direct` will opt for the **direct** and **transitive**. Alternatively, `--resolution=lowest-direct` will opt for the
**lowest** compatible versions for all **direct** dependencies, while using the **latest** **lowest** compatible versions for all **direct** dependencies, while using the **latest**
compatible versions for all **transitive** dependencies. This distinction can be particularly useful 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 for library authors who wish to test against the lowest supported versions of direct dependencies
@ -68,36 +68,37 @@ By default, uv will accept pre-release versions during dependency resolution in
(e.g., `flask>=2.0.0rc1`). (e.g., `flask>=2.0.0rc1`).
1. If _all_ published versions of a package are pre-releases. 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 If dependency resolution fails due to a transitive pre-release, uv will prompt the user to re-run
re-run with `--prerelease=allow`, to allow pre-releases for all dependencies. with `--prerelease=allow`, to allow pre-releases for all dependencies.
Alternatively, you can add the transitive dependency to your `requirements.in` file with a 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 pre-release specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific
dependency. dependency.
Pre-releases are [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) Pre-releases are [notoriously
to model, and are a frequent source of bugs in other packaging tools. uv's pre-release handling difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to model, and are a
is _intentionally_ limited and _intentionally_ requires user opt-in for pre-releases, to ensure frequent source of bugs in other packaging tools. uv's pre-release handling is _intentionally_
correctness. 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) For more, see ["Pre-release compatibility"](../pip/compatibility.md#pre-release-compatibility)
## Dependency overrides ## Dependency overrides
Historically, `pip` has supported "constraints" (`-c constraints.txt`), which allows users to Historically, `pip` has supported "constraints" (`-c constraints.txt`), which allows users to narrow
narrow the set of acceptable versions for a given package. the set of acceptable versions for a given package.
uv supports constraints, but also takes this concept further by allowing users to _override_ the 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`). 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 In short, overrides allow the user to lie to the resolver by overriding the declared dependencies of
of a package. Overrides are a useful last resort for cases in which the user knows that a a package. Overrides are a useful last resort for cases in which the user knows that a dependency is
dependency is compatible with a newer version of a package than the package declares, but the compatible with a newer version of a package than the package declares, but the package has not yet
package has not yet been updated to declare that compatibility. been updated to declare that compatibility.
For example, if a transitive dependency declares `pydantic>=1.0,<2.0`, but the user knows that For example, if a transitive dependency declares `pydantic>=1.0,<2.0`, but the user knows that the
the package is compatible with `pydantic>=2.0`, the user can override the declared dependency package is compatible with `pydantic>=2.0`, the user can override the declared dependency with
with `pydantic>=2.0,<3` to allow the resolver to continue. `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 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 a package, overrides _can_ expand the set of acceptable versions for a package, providing an escape
@ -105,34 +106,34 @@ hatch for erroneous upper version bounds.
## Multi-platform resolution ## Multi-platform resolution
By default, uv's `pip-compile` command produces a resolution that's known to be compatible with By default, uv's `pip-compile` command produces a resolution that's known to be compatible with the
the current platform and Python version. current platform and Python version.
uv also supports a machine agnostic resolution. uv supports writing multiplatform resolutions in both a `requirements.txt` format uv also supports a machine agnostic resolution. uv supports writing multiplatform resolutions in
and uv-specific (`uv.lock`) format. both a `requirements.txt` format and uv-specific (`uv.lock`) format.
If using uv's `pip compile`, the `--universal` flag will generate a resolution that is compatible with all operating systems, If using uv's `pip compile`, the `--universal` flag will generate a resolution that is compatible
architectures, and Python implementations. In universal mode, the current Python version (or provided `--python-version`) with all operating systems, architectures, and Python implementations. In universal mode, the
will be treated as a lower bound. For example, `--universal --python-version 3.7` would produce a universal resolution current Python version (or provided `--python-version`) will be treated as a lower bound. For
for Python 3.7 and later. example, `--universal --python-version 3.7` would produce a universal resolution for Python 3.7 and
later.
If using uv's [project](../guides/projects.md) interface, the machine agnostic resolution will be used If using uv's [project](../guides/projects.md) interface, the machine agnostic resolution will be
automatically and a `uv.lock` file will be created. The lockfile can also be created with an explicit `uv lock` used automatically and a `uv.lock` file will be created. The lockfile can also be created with an
invocation. explicit `uv lock` invocation.
uv also supports resolving for specific alternate platforms and Python versions via the uv also supports resolving for specific alternate platforms and Python versions via the
`--python-platform` and `--python-version` command line arguments. `--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 For example, if you're running uv on macOS, but want to resolve for Linux, you can run `uv pip
`uv pip compile --python-platform=linux requirements.in` to produce a `manylinux2014`-compatible compile --python-platform=linux requirements.in` to produce a `manylinux2014`-compatible resolution.
resolution.
Similarly, if you're running uv on Python 3.9, but want to resolve for Python 3.8, you can run Similarly, if you're running uv on Python 3.9, but want to resolve for Python 3.8, you can run `uv
`uv pip compile --python-version=3.8 requirements.in` to produce a Python 3.8-compatible resolution. 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 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 a specific platform and Python version, enabling users to generate multiple lockfiles for different
different environments from a single machine. environments from a single machine.
!!! note !!! note
@ -146,13 +147,15 @@ different environments from a single machine.
## Time-restricted reproducible resolutions ## Time-restricted reproducible resolutions
uv supports an `--exclude-newer` option to limit resolution to distributions published before a specific uv supports an `--exclude-newer` option to limit resolution to distributions published before a
date, allowing reproduction of installations regardless of new package releases. The date may be specified specific date, allowing reproduction of installations regardless of new package releases. The date
as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamp (e.g., `2006-12-02T02:07:43Z`) or may be specified as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamp (e.g.,
UTC date in the same format (e.g., `2006-12-02`). `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/). Note the package index must support the `upload-time` field as specified in [`PEP
If the field is not present for a given distribution, the distribution will be treated as unavailable. 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 To ensure reproducibility, messages for unsatisfiable resolutions will not mention that
due to the `--exclude-newer` flag — newer distributions will be treated as if they do not exist. distributions were excluded due to the `--exclude-newer` flag — newer distributions will be treated
as if they do not exist.

47
docs/concepts/tools.md
View file

@ -1,18 +1,27 @@
# Tools # Tools
Tools are Python packages that provide command-line interfaces. Tools can be invoked without installation using `uvx`, in which case their dependencies are installed in a temporary virtual environment isolated from the current project. Alternatively, tools can be installed with `uv tool install`, in which case their executables are placed in the `PATH` — an isolated virtual environment is still used but it is not treated as disposable. Tools are Python packages that provide command-line interfaces. Tools can be invoked without
installation using `uvx`, in which case their dependencies are installed in a temporary virtual
environment isolated from the current project. Alternatively, tools can be installed with `uv tool
install`, in which case their executables are placed in the `PATH` — an isolated virtual environment
is still used but it is not treated as disposable.
!!! note !!! note
See the [tools guide](../guides/tools.md) for an introduction to working with the tools interface — this document discusses details of tool management. See the [tools guide](../guides/tools.md) for an introduction to working with the tools
interface — this document discusses details of tool management.
## Tool environments ## Tool environments
Tools are installed into virtual environments which are created in the uv tools directory. When running tools with `uvx` or `uv tool run`, the virtual environments are stored in the uv cache directory and are treated as disposable. Tools are installed into virtual environments which are created in the uv tools directory. When
running tools with `uvx` or `uv tool run`, the virtual environments are stored in the uv cache
directory and are treated as disposable.
### Tools directory ### Tools directory
By default, the uv tools directory is named `tools` and is in the uv application state directory, e.g., `~/.local/share/uv/tools`. The location may be customized with the `UV_TOOL_DIR` environment variable. By default, the uv tools directory is named `tools` and is in the uv application state directory,
e.g., `~/.local/share/uv/tools`. The location may be customized with the `UV_TOOL_DIR` environment
variable.
To display the path to the tool installation directory: To display the path to the tool installation directory:
@ -20,11 +29,13 @@ To display the path to the tool installation directory:
$ uv tool dir $ uv tool dir
``` ```
Tool environments are placed in a directory with the same name as the tool package, e.g., `.../tools/<name>`. Tool environments are placed in a directory with the same name as the tool package, e.g.,
`.../tools/<name>`.
### Mutating tool environments ### Mutating tool environments
Tool environments are _not_ intended to be mutated directly. It is strongly recommended never to mutate a tool environment manually with a `pip` operation. Tool environments are _not_ intended to be mutated directly. It is strongly recommended never to
mutate a tool environment manually with a `pip` operation.
Tool environments may be either mutated or re-created by subsequent `uv tool install` operations. Tool environments may be either mutated or re-created by subsequent `uv tool install` operations.
@ -74,15 +85,22 @@ The `--with` option supports package specifications, so a specific version can b
$ uvx --with <extra-package>==<version> <tool-package> $ uvx --with <extra-package>==<version> <tool-package>
``` ```
If the requested version conflicts with the requirements of the tool package, package resolution will fail and the command will error. If the requested version conflicts with the requirements of the tool package, package resolution
will fail and the command will error.
## Tool executables ## Tool executables
Tool executables are all console entry points, script entry points, and binary scripts provided by a Python package. Tool executables are symlinked into the `bin` directory on Unix and copied on Windows. Tool executables are all console entry points, script entry points, and binary scripts provided by a
Python package. Tool executables are symlinked into the `bin` directory on Unix and copied on
Windows.
### `bin` directory ### `bin` directory
Executables are installed into the user's `bin` directory following the XDG standard, e.g., `~/.local/bin`. Unlike other directory schemes in uv, the XDG standard is used on _all platforms_ notably including Windows and macOS — there is no clear alternative location to place executables on these platforms. The installation directory is determined from the first available environment variable: Executables are installed into the user's `bin` directory following the XDG standard, e.g.,
`~/.local/bin`. Unlike other directory schemes in uv, the XDG standard is used on _all platforms_
notably including Windows and macOS — there is no clear alternative location to place executables on
these platforms. The installation directory is determined from the first available environment
variable:
- `$XDG_BIN_HOME` - `$XDG_BIN_HOME`
- `$XDG_DATA_HOME/../bin` - `$XDG_DATA_HOME/../bin`
@ -92,11 +110,15 @@ Executables provided by dependencies of tool packages are not installed.
### The `PATH` ### The `PATH`
The `bin` directory must be in the `PATH` variable for tool executables to be available from the shell. If it is not in the `PATH`, a warning will be displayed. The `uv tool update-shell` command can be used to add the `bin` directory to the `PATH` in common shell configuration files. The `bin` directory must be in the `PATH` variable for tool executables to be available from the
shell. If it is not in the `PATH`, a warning will be displayed. The `uv tool update-shell` command
can be used to add the `bin` directory to the `PATH` in common shell configuration files.
### Overriding executables ### Overriding executables
Installation of tools will not overwrite executables in the `bin` directory that were not previously installed by uv. For example, if `pipx` has been used to install a tool, `uv tool install` will fail. The `--force` flag can be used to override this behavior. Installation of tools will not overwrite executables in the `bin` directory that were not previously
installed by uv. For example, if `pipx` has been used to install a tool, `uv tool install` will
fail. The `--force` flag can be used to override this behavior.
## `uv tool run` vs `uv run` ## `uv tool run` vs `uv run`
@ -111,4 +133,5 @@ 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 `--with` option is not needed — the required package is inferred from the command name.
- The temporary environment is cached in a dedicated location. - The temporary environment is cached in a dedicated location.
- The `--isolated` flag is not needed — tools are always run isolated from the project. - The `--isolated` 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. - If a tool is already installed, `uv tool run` will use the installed version but `uv run` will
not.

28
docs/concepts/workspaces.md
View file

@ -1,18 +1,18 @@
# Workspaces # Workspaces
Workspaces help organize large codebases by splitting them into multiple packages with Workspaces help organize large codebases by splitting them into multiple packages with independent
independent dependencies. dependencies.
When using the `uv pip` interface, workspace dependencies behave like automatic editable path When using the `uv pip` interface, workspace dependencies behave like automatic editable path
dependencies. Using the uv project interface, all of the workspace packages are locked together. dependencies. Using the uv project interface, all of the workspace packages are locked together. `uv
`uv run` installs only the current package (unless overridden with `--package`) and its workspace and run` installs only the current package (unless overridden with `--package`) and its workspace and
non-workspace dependencies. non-workspace dependencies.
## Configuration ## Configuration
A workspace can be created 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
root. This table contains `members` (mandatory) and `exclude` (optional), with lists of globs of workspace root. This table contains `members` (mandatory) and `exclude` (optional), with lists of
directories: globs of directories:
```toml title="pyproject.toml" ```toml title="pyproject.toml"
[tool.uv.workspace] [tool.uv.workspace]
@ -20,14 +20,16 @@ members = ["packages/*", "examples/*"]
exclude = ["example/excluded_example"] exclude = ["example/excluded_example"]
``` ```
If `tool.uv.sources` is defined in the 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
overridden in the `tool.uv.sources` of a specific project. in the `tool.uv.sources` of a specific project.
## Common structures ## Common structures
There a two main workspace structures: A **root package with helpers** and a **flat workspace**. There a two main workspace structures: A **root package with helpers** and a **flat workspace**.
The root workspace layout defines one main package in the root of the repository, with helper packages in `packages`. In this example `albatross/pyproject.toml` has both a `project` section and a `tool.uv.workspace` section. The root workspace layout defines one main package in the root of the repository, with helper
packages in `packages`. In this example `albatross/pyproject.toml` has both a `project` section and
a `tool.uv.workspace` section.
```text ```text
albatross albatross
@ -52,9 +54,9 @@ albatross
└── main.py └── main.py
``` ```
In the flat layout, all packages are in the `packages` directory, and the root In the flat layout, all packages are in the `packages` directory, and the root `pyproject.toml`
`pyproject.toml` defines a so-called virtual workspace. In this example `albatross/pyproject.toml` has only a `tool.uv.workspace` section, defines a so-called virtual workspace. In this example `albatross/pyproject.toml` has only a
but no `project`. `tool.uv.workspace` section, but no `project`.
```text ```text
albatross albatross

38
docs/configuration/authentication.md
View file

@ -2,25 +2,31 @@
## Git authentication ## Git authentication
uv allows packages to be installed from Git and supports the following schemes for authenticating with private uv allows packages to be installed from Git and supports the following schemes for authenticating
repositories. with private repositories.
Using SSH: Using SSH:
- `git+ssh://git@<hostname>/...` (e.g. `git+ssh://git@github.com/astral-sh/uv`) - `git+ssh://git@<hostname>/...` (e.g. `git+ssh://git@github.com/astral-sh/uv`)
- `git+ssh://git@<host>/...` (e.g. `git+ssh://git@github.com-key-2/astral-sh/uv`) - `git+ssh://git@<host>/...` (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. 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: Using a password or token:
- `git+https://<user>:<token>@<hostname>/...` (e.g. `git+https://git:github_pat_asdf@github.com/astral-sh/uv`) - `git+https://<user>:<token>@<hostname>/...` (e.g.
`git+https://git:github_pat_asdf@github.com/astral-sh/uv`)
- `git+https://<token>@<hostname>/...` (e.g. `git+https://github_pat_asdf@github.com/astral-sh/uv`) - `git+https://<token>@<hostname>/...` (e.g. `git+https://github_pat_asdf@github.com/astral-sh/uv`)
- `git+https://<user>@<hostname>/...` (e.g. `git+https://git@github.com/astral-sh/uv`) - `git+https://<user>@<hostname>/...` (e.g. `git+https://git@github.com/astral-sh/uv`)
When using a GitHub personal access token, the username is arbitrary. GitHub does not support logging in with password directly, although other hosts may. If a username is provided without credentials, you will be prompted to enter them. 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. 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 ## HTTP authentication
@ -32,12 +38,12 @@ Authentication can come from the following sources, in order of precedence:
- A [`netrc`](https://everything.curl.dev/usingcurl/netrc) configuration file - A [`netrc`](https://everything.curl.dev/usingcurl/netrc) configuration file
- A [keyring](https://github.com/jaraco/keyring) provider (requires opt-in) - 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 If authentication is found for a single net location (scheme, host, and port), it will be cached for
of the command and used for other queries to that net location. Authentication is not cached across invocations of the duration of the command and used for other queries to that net location. Authentication is not
uv. cached across invocations of uv.
Note `--keyring-provider subprocess` or `UV_KEYRING_PROVIDER=subprocess` must be provided to enable keyring-based Note `--keyring-provider subprocess` or `UV_KEYRING_PROVIDER=subprocess` must be provided to enable
authentication. keyring-based authentication.
Authentication may be used for hosts specified in the following contexts: Authentication may be used for hosts specified in the following contexts:
@ -46,8 +52,8 @@ Authentication may be used for hosts specified in the following contexts:
- `find-links` - `find-links`
- `package @ https://...` - `package @ https://...`
See the [`pip` compatibility guide](../pip/compatibility.md#registry-authentication) for details on differences from See the [`pip` compatibility guide](../pip/compatibility.md#registry-authentication) for details on
`pip`. differences from `pip`.
## Custom CA certificates ## Custom CA certificates
@ -65,8 +71,10 @@ variable to the path of the certificate bundle, to instruct uv to use that file
system's trust store. system's trust store.
If client certificate authentication (mTLS) is desired, set the `SSL_CLIENT_CERT` environment 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. variable to the path of the PEM formatted file containing the certificate followed by the private
key.
## Authentication with alternative package indexes ## Authentication with alternative package indexes
See the [alternative indexes integration guide](../guides/integration/alternative-indexes.md) for details on authentication with popular alternative Python package indexes. See the [alternative indexes integration guide](../guides/integration/alternative-indexes.md) for
details on authentication with popular alternative Python package indexes.

51
docs/configuration/environment.md
View file

@ -4,8 +4,8 @@ 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 - `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. 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 - `UV_EXTRA_INDEX_URL`: Equivalent to the `--extra-index-url` command-line argument. If set, uv will
will use this space-separated list of URLs as additional indexes when searching for packages. 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 - `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. 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 - `UV_NO_CACHE`: Equivalent to the `--no-cache` command-line argument. If set, uv will not use the
@ -14,30 +14,28 @@ uv accepts the following command-line arguments as environment variables:
`lowest-direct`, uv will install the lowest compatible versions of all direct dependencies. `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 - `UV_PRERELEASE`: Equivalent to the `--prerelease` command-line argument. For example, if set to
`allow`, uv will allow pre-release versions for all dependencies. `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 - `UV_SYSTEM_PYTHON`: Equivalent to the `--system` command-line argument. If set to `true`, uv will
will use the first Python interpreter found in the system `PATH`. use the first Python interpreter found in the system `PATH`. WARNING: `UV_SYSTEM_PYTHON=true` is
WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI) or intended for use in continuous integration (CI) or containerized environments and should be used
containerized environments and should be used with caution, as modifying the system Python with caution, as modifying the system Python can lead to unexpected behavior.
can lead to unexpected behavior. - `UV_PYTHON`: Equivalent to the `--python` command-line argument. If set to a path, uv will use
- `UV_PYTHON`: Equivalent to the `--python` command-line argument. If set to a path, uv will this Python interpreter for all operations.
use this Python interpreter for all operations.
- `UV_BREAK_SYSTEM_PACKAGES`: Equivalent to the `--break-system-packages` command-line argument. If - `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 set to `true`, uv will allow the installation of packages that conflict with system-installed
packages. packages. WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration
WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration (CI) or (CI) or containerized environments and should be used with caution, as modifying the system Python
containerized environments and should be used with caution, as modifying the system Python
can lead to unexpected behavior. can lead to unexpected behavior.
- `UV_NATIVE_TLS`: Equivalent to the `--native-tls` command-line argument. If set to `true`, uv - `UV_NATIVE_TLS`: Equivalent to the `--native-tls` command-line argument. If set to `true`, uv will
will use the system's trust store instead of the bundled `webpki-roots` crate. 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 - `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 set to `unsafe-any-match`, uv will consider versions of a given package available across all index
index URLs, rather than limiting its search to the first index URL that contains the package. 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_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 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 - `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. 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 - `UV_LINK_MODE`: Equivalent to the `--link-mode` command-line argument. If set, uv will use this as
as a link mode. a link mode.
- `UV_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` command-line argument. If set, - `UV_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` command-line argument. If set,
uv will skip isolation when building source distributions. uv will skip isolation when building source distributions.
- `UV_CUSTOM_COMPILE_COMMAND`: Used to override uv in the output header of the `requirements.txt` - `UV_CUSTOM_COMPILE_COMMAND`: Used to override uv in the output header of the `requirements.txt`
@ -47,8 +45,8 @@ uv accepts the following command-line arguments as environment variables:
will use this value as the keyring provider. will use this value as the keyring provider.
- `UV_CONFIG_FILE`: Equivalent to the `--config-file` command-line argument. Expects a path to a - `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. local `uv.toml` file to use as the configuration file.
- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that uv - `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that uv will
will perform at any given time. perform at any given time.
- `UV_CONCURRENT_BUILDS`: Sets the maximum number of source distributions that uv will build - `UV_CONCURRENT_BUILDS`: Sets the maximum number of source distributions that uv will build
concurrently at any given time. concurrently at any given time.
- `UV_CONCURRENT_INSTALLS`: Used to control the number of threads used when installing and unzipping - `UV_CONCURRENT_INSTALLS`: Used to control the number of threads used when installing and unzipping
@ -66,13 +64,14 @@ In addition, uv respects the following environment variables:
file containing both the certificate and the private key in PEM format. 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 - `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 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) enable trace-level logging. See the [tracing
documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax)
for more. for more.
- `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`: The proxy to use for all HTTP/HTTPS requests. - `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 - `HTTP_TIMEOUT` (or `UV_HTTP_TIMEOUT`): If set, uv will use this value (in seconds) as the timeout
for HTTP reads (default: 30 s). for HTTP reads (default: 30 s).
- `PYC_INVALIDATION_MODE`: The validation modes to use when run with `--compile`. - `PYC_INVALIDATION_MODE`: The validation modes to use when run with `--compile`. See:
See: [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode). [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode).
- `VIRTUAL_ENV`: Used to detect an activated virtual environment. - `VIRTUAL_ENV`: Used to detect an activated virtual environment.
- `CONDA_PREFIX`: Used to detect an activated Conda 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). - `PROMPT`: Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).
@ -83,5 +82,7 @@ In addition, uv respects the following environment variables:
- `MACOSX_DEPLOYMENT_TARGET`: Used with `--python-platform macos` and related variants to set the - `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 deployment target (i.e., the minimum supported macOS version). Defaults to `12.0`, the
least-recent non-EOL macOS version at time of writing. 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). - `NO_COLOR`: Disable colors. Takes precedence over `FORCE_COLOR`. See
- `FORCE_COLOR`: Enforce colors regardless of TTY support. See [force-color.org](https://force-color.org). [no-color.org](https://no-color.org).
- `FORCE_COLOR`: Enforce colors regardless of TTY support. See
[force-color.org](https://force-color.org).

8
docs/configuration/files.md
View file

@ -5,16 +5,16 @@ 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 Specifically, uv will search for a `pyproject.toml` or `uv.toml` file in the current directory, or
in the nearest parent directory. in the nearest parent directory.
If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table. If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table. For
For example, to set a persistent index URL, add the following to a `pyproject.toml`: example, to set a persistent index URL, add the following to a `pyproject.toml`:
```toml title="project.toml" ```toml title="project.toml"
[tool.uv.pip] [tool.uv.pip]
index-url = "https://test.pypi.org/simple" 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 (If there is no such table, the `pyproject.toml` file will be ignored, and uv will continue
the directory hierarchy.) searching in the directory hierarchy.)
If a `uv.toml` file is found, uv will read from the `[pip]` table. For example: If a `uv.toml` file is found, uv will read from the `[pip]` table. For example:

3
docs/configuration/index.md
View file

@ -8,4 +8,5 @@ Read about the various ways to configure uv:
<!-- TODO(zanieb): Move generated settings reference to correct section --> <!-- TODO(zanieb): Move generated settings reference to correct section -->
Or, jump to the [settings reference](../settings.md) which enumerates the available configuration options. Or, jump to the [settings reference](../settings.md) which enumerates the available configuration
options.

15
docs/features.md
View file

@ -1,9 +1,11 @@
# Features # Features
uv supports the full Python development experience — from installing Python and hacking on simple scripts to working on large projects that support multiple Python versions and platforms. uv supports the full Python development experience — from installing Python and hacking on simple
scripts to working on large projects that support multiple Python versions and platforms.
uv's commands can be broken down into sections of discrete features, which can be used independently. uv's commands can be broken down into sections of discrete features, which can be used
independently.
## Python versions ## Python versions
@ -53,7 +55,8 @@ See the [guide on tools](./guides/tools.md) to get started.
## The pip interface ## The pip interface
Manually managing environments and packages — intended to be used in legacy workflows or cases where the high-level commands do not provide enough control. Manually managing environments and packages — intended to be used in legacy workflows or cases where
the high-level commands do not provide enough control.
Creating virtual environments (replacing `venv` and `virtualenv`): Creating virtual environments (replacing `venv` and `virtualenv`):
@ -61,7 +64,8 @@ Creating virtual environments (replacing `venv` and `virtualenv`):
See the documentation on [using environments](./pip/environments.md) for details. 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)): 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 install`: Install packages into the current environment.
- `uv pip show`: Show details about an installed package. - `uv pip show`: Show details about an installed package.
@ -86,7 +90,8 @@ See the documentation on [locking environments](./pip/compile.md) for details.
## Internal ## Internal
Managing and inspecting uv's state, such as the cache, storage directories, or performing a self-update: 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 clean`: Remove cache entries.
- `uv cache prune`: Remove outdated cache entries. - `uv cache prune`: Remove outdated cache entries.

12
docs/first-steps.md
View file

@ -2,7 +2,8 @@
uv only provides a command-line interface and must be used from a terminal. uv only provides a command-line interface and must be used from a terminal.
After [installing uv](./installation.md), you can check that uv is installed by running the `uv` command: After [installing uv](./installation.md), you can check that uv is installed by running the `uv`
command:
```console ```console
$ uv $ uv
@ -40,7 +41,8 @@ To view the help menu for a specific command, e.g., for `uv init`:
$ uv init --help $ uv init --help
``` ```
When using the `--help` flag, uv displays a condensed help menu. To view a longer help menu for a command, use `uv help`: When using the `--help` flag, uv displays a condensed help menu. To view a longer help menu for a
command, use `uv help`:
```console ```console
$ uv help $ uv help
@ -52,8 +54,10 @@ To view the long help menu for a specific command, e.g., for `uv init`:
$ uv help init $ uv help init
``` ```
When using the long help menu, uv will attempt to use `less` or `more` to "page" the output so it is not all displayed at once. To exit the pager, press `q`. When using the long help menu, uv will attempt to use `less` or `more` to "page" the output so it is
not all displayed at once. To exit the pager, press `q`.
## Next steps ## Next steps
Now that you've confirmed uv is installed and know how to get help, check out an [overview of features](./features.md) or jump straight into the [guides](./guides/index.md) to start using uv. Now that you've confirmed uv is installed and know how to get help, check out an [overview of
features](./features.md) or jump straight into the [guides](./guides/index.md) to start using uv.

3
docs/guides/index.md
View file

@ -14,4 +14,5 @@ Learn how to integrate uv with other software:
- [Using in GitHub Actions](./integration/github.md) - [Using in GitHub Actions](./integration/github.md)
- [Using with alternative package indexes](./integration/alternative-indexes.md) - [Using with alternative package indexes](./integration/alternative-indexes.md)
Or, explore the [concept documentation](../concepts/index.md) for comprehensive breakdown of each feature. Or, explore the [concept documentation](../concepts/index.md) for comprehensive breakdown of each
feature.

30
docs/guides/install-python.md
View file

@ -1,6 +1,8 @@
# Installing Python # Installing Python
If Python is already installed on your system, uv will [detect and use](#using-an-existing-python-installation) it without configuration. However, uv can also install and manage Python versions for you. If Python is already installed on your system, uv will [detect and
use](#using-an-existing-python-installation) it without configuration. However, uv can also install
and manage Python versions for you.
!!! tip !!! tip
@ -12,7 +14,8 @@ To install the latest Python version:
$ uv python install $ uv python install
``` ```
This will install a uv managed Python version even if there is already a Python installation on your system. This will install a uv managed Python version even if there is already a Python installation on your
system.
!!! note !!! note
@ -41,7 +44,8 @@ To install a specific Python version:
$ uv python install 3.12 $ uv python install 3.12
``` ```
See the [`python install`](../concepts/python-versions.md#installing-a-python-version) documentation for more details. See the [`python install`](../concepts/python-versions.md#installing-a-python-version) documentation
for more details.
## Viewing Python installations ## Viewing Python installations
@ -51,19 +55,24 @@ To view available and installed Python versions:
$ uv python list $ uv python list
``` ```
See the [`python list`](../concepts/python-versions.md#viewing-available-python-versions) documentation for more details. See the [`python list`](../concepts/python-versions.md#viewing-available-python-versions)
documentation for more details.
<!--TODO(zanieb): The above should probably link to a CLI reference and that content should be moved out of that file --> <!--TODO(zanieb): The above should probably link to a CLI reference and that content should be moved out of that file -->
## Automatic Python downloads ## Automatic Python downloads
Note that Python does not need to be explicitly installed to use uv. By default, uv will automatically download Python versions when they are required. For example, the following would download Python 3.12 if it was not installed: Note that Python does not need to be explicitly installed to use uv. By default, uv will
automatically download Python versions when they are required. For example, the following would
download Python 3.12 if it was not installed:
```console ```console
$ uv run --python 3.12 python -c 'print("hello world")' $ uv run --python 3.12 python -c 'print("hello world")'
``` ```
Even if a specific Python version is not requested, uv will download the latest version on demand. For example, the following will create a new virtual environment and download a managed Python version if Python is not found: Even if a specific Python version is not requested, uv will download the latest version on demand.
For example, the following will create a new virtual environment and download a managed Python
version if Python is not found:
```console ```console
$ uv venv $ uv venv
@ -75,6 +84,11 @@ Note that when an automatic Python installation occurs, the `python` command wil
## Using an existing Python installation ## Using an existing Python installation
uv will also use an existing Python installation if already present on your system. There is no configuration necessary for this behavior: uv will use the system Python if it satisfies the requirements of the command invocation. See the [Python discovery](../concepts/python-versions.md#discovery-order) documentation for details. uv will also use an existing Python installation if already present on your system. There is no
configuration necessary for this behavior: uv will use the system Python if it satisfies the
requirements of the command invocation. See the [Python
discovery](../concepts/python-versions.md#discovery-order) documentation for details.
To force uv to use the system Python, provide the `--python-preference only-system` option. See the [Python version preference](../concepts/python-versions.md#adjusting-python-version-preferences) documentation for more details. To force uv to use the system Python, provide the `--python-preference only-system` option. See the
[Python version preference](../concepts/python-versions.md#adjusting-python-version-preferences)
documentation for more details.

35
docs/guides/integration/alternative-indexes.md
View file

@ -1,14 +1,23 @@
# Using alternative package indexes # Using alternative package indexes
While uv uses the official Python Package Index (PyPI) by default, it also supports alternative package indexes. Most alternative indexes require various forms of authentication, which requires some initial setup. While uv uses the official Python Package Index (PyPI) by default, it also supports alternative
package indexes. Most alternative indexes require various forms of authentication, which requires
some initial setup.
## Azure Artifacts ## Azure Artifacts
uv can install packages from [Azure DevOps Artifacts](https://learn.microsoft.com/en-us/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget%2Cnugetserver). Authenticate to a feed using a [Personal Access Token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows) (PAT) or interactively using the [`keyring`](https://github.com/jaraco/keyring) package. uv can install packages from [Azure DevOps
Artifacts](https://learn.microsoft.com/en-us/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget%2Cnugetserver).
Authenticate to a feed using a [Personal Access
Token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows)
(PAT) or interactively using the [`keyring`](https://github.com/jaraco/keyring) package.
### Using a PAT ### Using a PAT
If there is a PAT available (eg [`$(System.AccessToken)` in an Azure pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken)), credentials can be provided via the "Basic" HTTP authentication scheme. Include the PAT in the password field of the URL. A username must be included as well, but can be any string. If there is a PAT available (eg [`$(System.AccessToken)` in an Azure
pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken)),
credentials can be provided via the "Basic" HTTP authentication scheme. Include the PAT in the
password field of the URL. A username must be included as well, but can be any string.
```bash ```bash
# With the token stored in the `ADO_PAT` environment variable # With the token stored in the `ADO_PAT` environment variable
@ -17,11 +26,22 @@ export UV_EXTRA_INDEX_URL=https://dummy:$ADO_PAT@pkgs.dev.azure.com/{organisatio
### Using `keyring` ### Using `keyring`
If there is not a PAT available, authenticate to Artifacts using the [`keyring`](https://github.com/jaraco/keyring) package with [the `artifacts-keyring` plugin](https://github.com/Microsoft/artifacts-keyring). Because these two packages are required to authenticate to Azure Artifacts, they must be pre-installed from a source other than Artifacts. If there is not a PAT available, authenticate to Artifacts using the
[`keyring`](https://github.com/jaraco/keyring) package with [the `artifacts-keyring`
plugin](https://github.com/Microsoft/artifacts-keyring). Because these two packages are required to
authenticate to Azure Artifacts, they must be pre-installed from a source other than Artifacts.
The `artifacts-keyring` plugin wraps [the Azure Artifacts Credential Provider tool](https://github.com/microsoft/artifacts-credprovider). The credential provider supports a few different authentication modes including interactive login — see [the tool's documentation](https://github.com/microsoft/artifacts-credprovider) for information on configuration. The `artifacts-keyring` plugin wraps [the Azure Artifacts Credential Provider
tool](https://github.com/microsoft/artifacts-credprovider). The credential provider supports a few
different authentication modes including interactive login — see [the tool's
documentation](https://github.com/microsoft/artifacts-credprovider) for information on
configuration.
uv only supports using the `keyring` package in [subprocess mode](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#registry-authentication). The `keyring` executable must be in the `PATH`, i.e., installed globally or in the active environment. The `keyring` CLI requires a username in the URL, so the index URL must include the default username `VssSessionToken`. uv only supports using the `keyring` package in [subprocess
mode](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#registry-authentication). The
`keyring` executable must be in the `PATH`, i.e., installed globally or in the active environment.
The `keyring` CLI requires a username in the URL, so the index URL must include the default username
`VssSessionToken`.
```bash ```bash
# Pre-install keyring and the Artifacts plugin from the public PyPI # Pre-install keyring and the Artifacts plugin from the public PyPI
@ -36,4 +56,5 @@ export UV_EXTRA_INDEX_URL=https://VssSessionToken@pkgs.dev.azure.com/{organisati
## Other indexes ## Other indexes
uv is also known to work with JFrog's Artifactory, the Google Cloud Artifact Registry, and AWS Code Artifact. uv is also known to work with JFrog's Artifactory, the Google Cloud Artifact Registry, and AWS Code
Artifact.

13
docs/guides/integration/docker.md
View file

@ -2,7 +2,8 @@
## Running 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: A Docker image is published with a built version of uv available. To run a uv command in a
container:
```bash ```bash
docker run ghcr.io/astral-sh/uv --help docker run ghcr.io/astral-sh/uv --help
@ -34,7 +35,8 @@ In either case, it is best practice to pin to a specific uv version.
Once uv is installed in an image, it can be used to install some packages. Once uv is installed in an image, it can be used to install some packages.
The system Python environment is safe to use this context, since a container is already isolated. The `--system` flag can be used to install in the system environment: The system Python environment is safe to use this context, since a container is already isolated.
The `--system` flag can be used to install in the system environment:
```dockerfile title="Dockerfile" ```dockerfile title="Dockerfile"
RUN uv pip install --system ruff RUN uv pip install --system ruff
@ -73,7 +75,9 @@ RUN uv pip install -r requirements.txt
## Installing a project ## Installing a project
When installing a project alongside requirements, it is prudent to separate copying the requirements from the rest of the source code. This allows the dependencies of the project (which do not change often) to be cached separately from the project itself (which changes very frequently). When installing a project alongside requirements, it is prudent to separate copying the requirements
from the rest of the source code. This allows the dependencies of the project (which do not change
often) to be cached separately from the project itself (which changes very frequently).
```dockerfile title="Dockerfile" ```dockerfile title="Dockerfile"
COPY pyproject.toml . COPY pyproject.toml .
@ -95,7 +99,8 @@ RUN --mount=from=uv,source=/uv,target=/bin/uv \
### Caching ### Caching
A [cache mount](https://docs.docker.com/build/guide/mounts/#add-a-cache-mount) can be used to improve performance across builds: A [cache mount](https://docs.docker.com/build/guide/mounts/#add-a-cache-mount) can be used to
improve performance across builds:
```dockerfile title="Dockerfile" ```dockerfile title="Dockerfile"
RUN --mount=type=cache,target=/root/.cache/uv \ RUN --mount=type=cache,target=/root/.cache/uv \

13
docs/guides/integration/github.md
View file

@ -109,7 +109,8 @@ steps:
run: uv python install ${{ 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 will not respect the project's pinned Python version. Alternatively, the official GitHub `setup-python` action can be used. This is generally faster, but
will not respect the project's pinned Python version.
```yaml title="example.yml" ```yaml title="example.yml"
steps: steps:
@ -121,7 +122,8 @@ steps:
## Syncing and running ## Syncing and running
Once uv and Python are installed, the project can be installed with `uv sync` and commands can be run in the environment with `uv run`: Once uv and Python are installed, the project can be installed with `uv sync` and commands can be
run in the environment with `uv run`:
```yaml title="example.yml" ```yaml title="example.yml"
steps: steps:
@ -137,7 +139,9 @@ steps:
## Using `uv pip` ## Using `uv pip`
If using the `uv pip` interface instead of the uv project interface, uv requires a virtual environment by default. To allow installing packages into the system environment, use the `--system` flag on all `uv` invocations or set the `UV_SYSTEM_PYTHON` variable. If using the `uv pip` interface instead of the uv project interface, uv requires a virtual
environment by default. To allow installing packages into the system environment, use the `--system`
flag on all `uv` invocations or set the `UV_SYSTEM_PYTHON` variable.
### Setting `UV_SYSTEM_PYTHON` ### Setting `UV_SYSTEM_PYTHON`
@ -178,7 +182,8 @@ steps:
UV_SYSTEM_PYTHON: 1 UV_SYSTEM_PYTHON: 1
``` ```
Now, `uv pip` can modify the system environment without creating and activating a virtual environment. Now, `uv pip` can modify the system environment without creating and activating a virtual
environment.
```yaml title="example.yml" ```yaml title="example.yml"
steps: steps:

3
docs/guides/integration/pre-commit.md
View file

@ -1,6 +1,7 @@
# Using uv in pre-commit # 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). 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`: To compile requirements via pre-commit, add the following to the `.pre-commit-config.yaml`:

65
docs/guides/projects.md
View file

@ -1,6 +1,7 @@
# Working on projects # Working on projects
uv is capable of managing Python projects using a `pyproject.toml` with a `[project]` metadata table. uv is capable of managing Python projects using a `pyproject.toml` with a `[project]` metadata
table.
## Creating a new project ## Creating a new project
@ -32,21 +33,20 @@ This will create the following directory structure:
### Working on an existing project ### Working on an existing project
If your project already contains a standard `pyproject.toml`, you can start If your project already contains a standard `pyproject.toml`, you can start using uv without any
using uv without any extra work. Commands like `uv add` and `uv run` will extra work. Commands like `uv add` and `uv run` will create a lockfile and virtual environment the
create a lockfile and virtual environment the first time they are used. first time they are used.
If you are migrating from an alternative Python package manager, you may need to If you are migrating from an alternative Python package manager, you may need to edit your
edit your `pyproject.toml` manually before using uv. uv uses a `[tool.uv]` section `pyproject.toml` manually before using uv. uv uses a `[tool.uv]` section in the `pyproject.toml` to
in the `pyproject.toml` to support features that are not yet included in the `pyproject.toml` standard, such as development dependencies. Alternative Python package managers may use support features that are not yet included in the `pyproject.toml` standard, such as development
different sections or format. dependencies. Alternative Python package managers may use different sections or format.
## Project structure ## Project structure
A project consists of a few important parts that work together and allow uv to A project consists of a few important parts that work together and allow uv to manage your project.
manage your project. Along with the files created by `uv init`, uv will create a Along with the files created by `uv init`, uv will create a virtual environment and `uv.lock` file
virtual environment and `uv.lock` file in the root of your project the first time you in the root of your project the first time you run a project command.
run a project command.
### `pyproject.toml` ### `pyproject.toml`
@ -64,10 +64,9 @@ dependencies = []
dev-dependencies = [] dev-dependencies = []
``` ```
This is where you specify dependencies, as well as details about the project This is where you specify dependencies, as well as details about the project such as it's
such as it's description or license. You can edit this file manually, or use description or license. You can edit this file manually, or use commands like `uv add` and `uv
commands like `uv add` and `uv remove` to manage your project through the remove` to manage your project through the CLI.
CLI.
!!! tip !!! tip
@ -75,34 +74,31 @@ CLI.
### `.venv` ### `.venv`
The `.venv` folder contains your project's virtual environment, a Python The `.venv` folder contains your project's virtual environment, a Python environment that is
environment that is isolated from the rest of your system. This is where uv will isolated from the rest of your system. This is where uv will install your project's dependencies.
install your project's dependencies.
### `uv.lock` ### `uv.lock`
`uv.lock` is a cross-platform lockfile that contains exact information about your `uv.lock` is a cross-platform lockfile that contains exact information about your project's
project's dependencies. Unlike the `pyproject.toml` which is used to specify the dependencies. Unlike the `pyproject.toml` which is used to specify the broad requirements of your
broad requirements of your project, the lockfile contains the exact resolved versions project, the lockfile contains the exact resolved versions that are installed in the virtual
that are installed in the virtual environment. This file should be checked into version environment. This file should be checked into version control, allowing for consistent and
control, allowing for consistent and reproducible installations across machines. reproducible installations across machines.
`uv.lock` is a human-readable TOML file but is managed by uv and should not be `uv.lock` is a human-readable TOML file but is managed by uv and should not be edited manually.
edited manually.
## Running commands ## Running commands
`uv run` can be used to run arbitrary scripts or commands in your project `uv run` can be used to run arbitrary scripts or commands in your project environment. This ensures
environment. This ensures that the lockfile and virtual environment are that the lockfile and virtual environment are up-to-date before executing a given command:
up-to-date before executing a given command:
```console ```console
$ uv run python my_script.py $ uv run python my_script.py
$ uv run flask run -p 3000 $ uv run flask run -p 3000
``` ```
Alternatively, you can use `uv sync` to manually synchronize the lockfile and Alternatively, you can use `uv sync` to manually synchronize the lockfile and virtual environment
virtual environment before executing a command: before executing a command:
```console ```console
$ uv sync $ uv sync
@ -116,8 +112,8 @@ $ python my_script.py
## Managing dependencies ## Managing dependencies
You can add dependencies to your `pyproject.toml` with the `uv add` command. You can add dependencies to your `pyproject.toml` with the `uv add` command. This will also update
This will also update the lockfile and virtual environment: the lockfile and virtual environment:
```console ```console
$ uv add requests $ uv add requests
@ -141,5 +137,4 @@ $ uv remove requests
## Next steps ## Next steps
See the [projects concept](../concepts/projects.md) documentation for more details about See the [projects concept](../concepts/projects.md) documentation for more details about projects.
projects.

37
docs/guides/scripts.md
View file

@ -1,7 +1,8 @@
# Running scripts # Running scripts
A Python script is a file intended for standalone execution, e.g., with `python <script>.py`. Using uv to execute scripts will ensure that A Python script is a file intended for standalone execution, e.g., with `python <script>.py`. Using
script dependencies are properly managed inside and outside of projects. uv to execute scripts will ensure that script dependencies are properly managed inside and outside
of projects.
## Running a script without dependencies ## Running a script without dependencies
@ -47,7 +48,9 @@ $ uv run example.py hello world!
hello world! hello world!
``` ```
Note that if you use `uv run` in a _project_, i.e. a directory with a `pyproject.toml`, it will install the current project before running the script. If your script does not depend on the project, use the `--isolated` flag to skip this: Note that if you use `uv run` in a _project_, i.e. a directory with a `pyproject.toml`, it will
install the current project before running the script. If your script does not depend on the
project, use the `--isolated` flag to skip this:
```console ```console
# Note, it is important that the flag comes _before_ the script # Note, it is important that the flag comes _before_ the script
@ -58,8 +61,12 @@ See the [projects guide](./projects.md) for more details on working in projects.
## Running a script with dependencies ## Running a script with dependencies
When your script requires other packages, they must be installed into the environment that the script runs in. uv prefers to create these environments on-demand instead of using a long-lived virtual environment with manually managed dependencies. This requires explicit declaration When your script requires other packages, they must be installed into the environment that the
of dependencies that are required for the script. Generally, it's recommended to use a [project](./projects.md) or [inline metadata](#declaring-script-dependencies) to declare dependencies, but uv supports requesting dependencies per invocation as well. script runs in. uv prefers to create these environments on-demand instead of using a long-lived
virtual environment with manually managed dependencies. This requires explicit declaration of
dependencies that are required for the script. Generally, it's recommended to use a
[project](./projects.md) or [inline metadata](#declaring-script-dependencies) to declare
dependencies, but uv supports requesting dependencies per invocation as well.
For example, the following script requires `rich`. For example, the following script requires `rich`.
@ -96,13 +103,17 @@ $ uv run --with 'rich>12,<13' example.py
Multiple dependencies can be requested by repeating with `--with` option. Multiple dependencies can be requested by repeating with `--with` option.
Note that if `uv run` is used in a _project_, these dependencies will be included _in addition_ to the project's dependencies. To opt-out of this behavior, use the `--isolated` flag. Note that if `uv run` is used in a _project_, these dependencies will be included _in addition_ to
the project's dependencies. To opt-out of this behavior, use the `--isolated` flag.
## Declaring script dependencies ## Declaring script dependencies
Python recently added a standard format for [inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata). This allows the dependencies for a script to be declared in the script itself. Python recently added a standard format for [inline script
metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata).
This allows the dependencies for a script to be declared in the script itself.
To use inline script metadata, include a `script` section at the top of the script and declare the dependencies using TOML: To use inline script metadata, include a `script` section at the top of the script and declare the
dependencies using TOML:
```python title="example.py" ```python title="example.py"
# /// script # /// script
@ -151,9 +162,12 @@ type Point = tuple[float, float]
print(Point) print(Point)
``` ```
uv will fetch the required Python version if it is not installed — see the documentation on [Python versions](../concepts/python-versions.md) for more details. Note that the `dependencies` field must be provided even if empty. uv will fetch the required Python version if it is not installed — see the documentation on [Python
versions](../concepts/python-versions.md) for more details. Note that the `dependencies` field must
be provided even if empty.
Note that when using inline script metadata, even if `uv run` is used in a _project_, the project's dependencies will be ignored. The `--isolated` flag is not required. Note that when using inline script metadata, even if `uv run` is used in a _project_, the project's
dependencies will be ignored. The `--isolated` flag is not required.
## Using different Python versions ## Using different Python versions
@ -177,4 +191,5 @@ $ uv run --python 3.10 example.py
3.10.13 3.10.13
``` ```
See the [Python version request](../concepts/python-versions.md#requesting-a-version) documentation for more details on requesting Python versions. See the [Python version request](../concepts/python-versions.md#requesting-a-version) documentation
for more details on requesting Python versions.

28
docs/guides/tools.md
View file

@ -1,6 +1,7 @@
# Using tools # Using tools
Many Python packages provide applications that can be used as tools. uv has specialized support for easily invoking and installing tools. Many Python packages provide applications that can be used as tools. uv has specialized support for
easily invoking and installing tools.
## Using `uvx` ## Using `uvx`
@ -40,9 +41,11 @@ $ uvx pycowsay hello from uv
## Commands with different package names ## Commands with different package names
When you invoke `uvx ruff`, uv installs the `ruff` package which provides the `ruff` command. However, sometimes the package and command names differ. When you invoke `uvx ruff`, uv installs the `ruff` package which provides the `ruff` command.
However, sometimes the package and command names differ.
The `--from` option can be used to invoke a command from a specific package, e.g. `http` which is provided by `httpie`: The `--from` option can be used to invoke a command from a specific package, e.g. `http` which is
provided by `httpie`:
```console ```console
$ uvx --from httpie http $ uvx --from httpie http
@ -90,7 +93,8 @@ $ uvx --with mkdocs-material mkdocs --help
## Installing tools ## Installing tools
If a tool is used often, it can be useful to install it to a persistent environment and add it to the `PATH` instead of invoking `uvx` repeatedly. If a tool is used often, it can be useful to install it to a persistent environment and add it to
the `PATH` instead of invoking `uvx` repeatedly.
To install `ruff`: To install `ruff`:
@ -98,7 +102,9 @@ To install `ruff`:
$ uv tool install ruff $ uv tool install ruff
``` ```
When a tool is installed, its executables are placed in a `bin` directory in the `PATH` which allows the tool to be run without uv. If it's not on the `PATH`, a warning will be displayed and `uv tool update-shell` can be used to add it to the `PATH`. When a tool is installed, its executables are placed in a `bin` directory in the `PATH` which allows
the tool to be run without uv. If it's not on the `PATH`, a warning will be displayed and `uv tool
update-shell` can be used to add it to the `PATH`.
After installing `ruff`, it should be available: After installing `ruff`, it should be available:
@ -106,15 +112,18 @@ After installing `ruff`, it should be available:
$ ruff --version $ ruff --version
``` ```
Unlike `uv pip install`, installing a tool does not make its modules available in the current environment. For example, the following command will fail: Unlike `uv pip install`, installing a tool does not make its modules available in the current
environment. For example, the following command will fail:
```console ```console
$ python -c "import ruff" $ python -c "import ruff"
``` ```
This isolation is important for reducing interactions and conflicts between dependencies of tools, scripts, and projects. This isolation is important for reducing interactions and conflicts between dependencies of tools,
scripts, and projects.
Unlike `uvx`, `uv tool install` operates on a _package_ and will install all executables provided by the tool. Unlike `uvx`, `uv tool install` operates on a _package_ and will install all executables provided by
the tool.
For example, the following will install the `http`, `https`, and `httpie` executables: For example, the following will install the `http`, `https`, and `httpie` executables:
@ -142,4 +151,5 @@ $ uv tool install mkdocs --with mkdocs-material
## Next steps ## Next steps
See the [tools concept](../concepts/tools.md) documentation for more details on how tools are managed. See the [tools concept](../concepts/tools.md) documentation for more details on how tools are
managed.

28
docs/index.md
View file

@ -24,17 +24,20 @@ An extremely fast Python package and project manager, written in Rust.
- 🐍 [Installs and manages](./guides/install-python.md) Python versions. - 🐍 [Installs and manages](./guides/install-python.md) Python versions.
- 🛠️ [Runs and installs](./guides/tools.md) Python applications. - 🛠️ [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). - ❇️ [Runs scripts](./guides/scripts.md), with support for [inline dependency
- 🗂️ Provides [comprehensive project management](./guides/projects.md), with a [universal lockfile](./concepts/projects.md#lockfile). 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. - 🏢 Supports Cargo-style [workspaces](./concepts/workspaces.md) for scalable projects.
- 🚀 A replacement for `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `virtualenv`, and more. - 🚀 A replacement for `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `virtualenv`, and more.
- ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip` - ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip` and
and `pip-tools` (`pip-compile` and `pip-sync`). `pip-tools` (`pip-compile` and `pip-sync`).
- 💾 Disk-space efficient, with a [global cache](./concepts/cache.md) for dependency deduplication. - 💾 Disk-space efficient, with a [global cache](./concepts/cache.md) for dependency deduplication.
- ⏬ Installable without Rust or Python via `curl` or `pip`. - ⏬ Installable without Rust or Python via `curl` or `pip`.
- 🖥️ Supports macOS, Linux, and Windows. - 🖥️ Supports macOS, Linux, and Windows.
uv is backed by [Astral](https://astral.sh), the creators of [Ruff](https://github.com/astral-sh/ruff). uv is backed by [Astral](https://astral.sh), the creators of
[Ruff](https://github.com/astral-sh/ruff).
## Getting started ## Getting started
@ -50,7 +53,8 @@ Or, on Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex" powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
``` ```
Then, check out the [first steps](./first-steps.md), see more [installation methods](./installation.md), or read on for a brief overview. Then, check out the [first steps](./first-steps.md), see more [installation
methods](./installation.md), or read on for a brief overview.
## Project management ## Project management
@ -159,10 +163,13 @@ See the [installing Python guide](./guides/install-python.md) to get started.
## The pip interface ## The pip interface
uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands with support for uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands with
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. 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 extends these interfaces with advanced features, such as dependency version overrides, multi-platform resolutions, reproducible resolutions, alternative resolution strategies, and more. uv extends these interfaces with advanced features, such as dependency version overrides,
multi-platform resolutions, reproducible resolutions, alternative resolution strategies, and more.
Compile requirements into a multi-platform requirements file: Compile requirements into a multi-platform requirements file:
@ -196,4 +203,5 @@ See the [uv pip documentation](./pip/index.md) to get started.
## Next steps ## Next steps
See the [first steps](./first-steps.md) or jump straight into the [guides](./guides/index.md) to start using uv. See the [first steps](./first-steps.md) or jump straight into the [guides](./guides/index.md) to
start using uv.

17
docs/installation.md
View file

@ -46,7 +46,8 @@ When the standalone installer is used, uv can upgrade itself:
uv self update uv self update
``` ```
When another installation method is used, self updates are disabled. Use the package manager's upgrade method instead. When another installation method is used, self updates are disabled. Use the package manager's
upgrade method instead.
## PyPI ## PyPI
@ -66,7 +67,10 @@ pip install uv
!!! note !!! note
There are prebuilt distributions (wheels) for many platforms; if not available for a given platform, uv will be built from source which requires a Rust toolchain to be installed. See the [contributing setup guide](https://github.com/astral-sh/uv/blob/main/CONTRIBUTING.md#setup) for details on building uv from source. There are prebuilt distributions (wheels) for many platforms; if not available for a given
platform, uv will be built from source which requires a Rust toolchain to be installed. See the
[contributing setup guide](https://github.com/astral-sh/uv/blob/main/CONTRIBUTING.md#setup)
for details on building uv from source.
## Homebrew ## Homebrew
@ -78,12 +82,15 @@ brew install uv
## Docker ## Docker
uv provides a Docker image at [`ghcr.io/astral-sh/uv`](https://github.com/astral-sh/uv/pkgs/container/uv). 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/integration/docker.md) for more details. See our guide on [using uv in Docker](./guides/integration/docker.md) for more details.
## GitHub Releases ## GitHub Releases
uv release artifacts can be downloaded directly from [GitHub Releases](https://github.com/astral-sh/uv/releases). uv release artifacts can be downloaded directly from [GitHub
Releases](https://github.com/astral-sh/uv/releases).
Each release page includes binaries for all supported platforms as well as instructions for using the standalone installer via `github.com` instead of `astral.sh`. Each release page includes binaries for all supported platforms as well as instructions for using
the standalone installer via `github.com` instead of `astral.sh`.

178
docs/pip/compatibility.md
View file

@ -3,12 +3,12 @@
uv is designed as a drop-in replacement for common `pip` and `pip-tools` workflows. 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 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 making meaningful changes to their packaging workflows; and, in most cases, swapping out `pip
`pip install` for `uv pip install` should "just work". 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 However, uv is _not_ intended to be an _exact_ clone of `pip`, and the further you stray from common
common `pip` workflows, the more likely you are to encounter differences in behavior. In some cases, `pip` workflows, the more likely you are to encounter differences in behavior. In some cases, those
those differences may be known and intentional; in others, they may be the result of implementation differences may be known and intentional; in others, they may be the result of implementation
details; and in others, they may be bugs. details; and in others, they may be bugs.
This document outlines the known differences between uv and `pip`, along with rationale, This document outlines the known differences between uv and `pip`, along with rationale,
@ -34,9 +34,9 @@ drawbacks:
behavior, and many users may _not_ expect uv to read configuration files intended for other behavior, and many users may _not_ expect uv to read configuration files intended for other
tools. tools.
Instead, uv supports its own environment variables, like `UV_INDEX_URL`. In the future, uv will Instead, uv supports its own environment variables, like `UV_INDEX_URL`. In the future, uv will also
also support persistent configuration in its own configuration file format (e.g., `pyproject.toml` support persistent configuration in its own configuration file format (e.g., `pyproject.toml` or
or `uv.toml` or similar). For more, see [#651](https://github.com/astral-sh/uv/issues/651). `uv.toml` or similar). For more, see [#651](https://github.com/astral-sh/uv/issues/651).
## Pre-release compatibility ## Pre-release compatibility
@ -46,28 +46,32 @@ By default, uv will accept pre-release versions during dependency resolution in
(e.g., `flask>=2.0.0rc1`). (e.g., `flask>=2.0.0rc1`).
1. If _all_ published versions of a package are pre-releases. 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 If dependency resolution fails due to a transitive pre-release, uv will prompt the user to re-run
re-run with `--prerelease=allow`, to allow pre-releases for all dependencies. with `--prerelease=allow`, to allow pre-releases for all dependencies.
Alternatively, you can add the transitive dependency to your `requirements.in` file with Alternatively, you can add the transitive dependency to your `requirements.in` file with pre-release
pre-release specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific dependency.
dependency.
In sum, uv needs to know upfront whether the resolver should accept pre-releases for a given 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 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)). 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) Pre-releases are [notoriously
to model, and are a frequent source of bugs in packaging tools. Even `pip`, which is viewed as a difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to model, and are a
reference implementation, has a number of open questions around pre-release handling ([#12469](https://github.com/pypa/pip/issues/12469), frequent source of bugs in packaging tools. Even `pip`, which is viewed as a reference
[#12470](https://github.com/pypa/pip/issues/12470), [#40505](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/20), etc.). 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 uv's pre-release handling is _intentionally_ limited and _intentionally_ requires user opt-in for
pre-releases, to ensure correctness. pre-releases, to ensure correctness.
In the future, uv _may_ support pre-release identifiers in transitive dependencies. However, it's 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 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) cover "dependency
and are instead focused on behavior for a _single_ version specifier. As such, there are unresolved 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 questions around the correct and intended behavior for pre-releases in the packaging ecosystem more
broadly. broadly.
@ -79,8 +83,8 @@ packages (and, e.g., disallowed on PyPI), they're common in the PyTorch ecosyste
to local versions _does_ support typical PyTorch workflows to succeed out-of-the-box. 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 [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. segment should typically be ignored when evaluating version specifiers, with a few exceptions. For
For example, `foo==1.2.3` should accept `1.2.3+local`, but `foo==1.2.3+local` should _not_ accept 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` `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 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 dependencies throughout the resolution, such that if you provide `foo==1.2.3+local` as a direct
@ -102,9 +106,9 @@ As compared to pip, the main differences in observed behavior are as follows:
## Packages that exist on multiple indexes ## Packages that exist on multiple indexes
In both uv and `pip`, users can specify multiple package indexes from which to search for In both uv and `pip`, users can specify multiple package indexes from which to search for the
the available versions of a given package. However, uv and `pip` differ in how they handle available versions of a given package. However, uv and `pip` differ in how they handle packages that
packages that exist on multiple indexes. exist on multiple indexes.
For example, imagine that a company publishes an internal version of `requests` on a private index 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 (`--extra-index-url`), but also allows installing packages from PyPI by default. In this case, the
@ -112,40 +116,41 @@ private `requests` would conflict with the public [`requests`](https://pypi.org/
on PyPI. on PyPI.
When uv searches for a package across multiple indexes, it will iterate over the indexes in order 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 (preferring the `--extra-index-url` over the default index), and stop searching as soon as it finds
finds a match. This means that if a package exists on multiple indexes, uv will limit its a match. This means that if a package exists on multiple indexes, uv will limit its candidate
candidate versions to those present in the first index that contains the package. 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 `pip`, meanwhile, will combine the candidate versions from all indexes, and select the best version
version from the combined set, though it makes [no guarantees around the order](https://github.com/pypa/pip/issues/5045#issuecomment-369521345) from the combined set, though it makes [no guarantees around the
in which it searches indexes, and expects that packages are unique up to name and version, even order](https://github.com/pypa/pip/issues/5045#issuecomment-369521345) in which it searches indexes,
across 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 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" 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 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 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/) package. See, for example, [the `torchtriton`
from December 2022. 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 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 `--index-strategy` command-line option, or the `UV_INDEX_STRATEGY` environment variable, which
variable, which supports the following values: supports the following values:
- `first-match` (default): Search for each package across all indexes, limiting the candidate - `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 versions to those present in the first index that contains the package, prioritizing the
`--extra-index-url` indexes over the default index URL. `--extra-index-url` indexes over the default index URL.
- `unsafe-first-match`: Search for each package across all indexes, but prefer the first index - `unsafe-first-match`: Search for each package across all indexes, but prefer the first index with
with a compatible version, even if newer versions are available on other indexes. 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 - `unsafe-best-match`: Search for each package across all indexes, and select the best version from
from the combined set of candidate versions. the combined set of candidate versions.
While `unsafe-best-match` is the closest to `pip`'s behavior, it exposes users to the risk of While `unsafe-best-match` is the closest to `pip`'s behavior, it exposes users to the risk of
"dependency confusion" attacks. "dependency confusion" attacks.
In the future, uv will support pinning packages to dedicated indexes (see: [#171](https://github.com/astral-sh/uv/issues/171)). In the future, uv will support pinning packages to dedicated indexes (see:
Additionally, [PEP 708](https://peps.python.org/pep-0708/) is a provisional standard that aims to [#171](https://github.com/astral-sh/uv/issues/171)). Additionally, [PEP
address the "dependency confusion" issue across package registries and installers. 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 ## Transitive direct URL dependencies for constraints and overrides
@ -175,26 +180,26 @@ search for a virtual environment named `.venv` in the current directory or any p
This differs from `pip`, which will install packages into a global environment if no virtual 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. 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 In uv, you can install into non-virtual environments by providing a path to a Python executable via
via the `--python /path/to/python` option, or via the `--system` flag, which installs into the the `--python /path/to/python` option, or via the `--system` flag, which installs into the first
first Python interpreter found on the `PATH`, like `pip`. Python interpreter found on the `PATH`, like `pip`.
In other words, uv inverts the default, requiring explicit opt-in to installing into the system 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 Python, which can lead to breakages and other complications, and should only be done in limited
circumstances. circumstances.
For more, see ["Using arbitrary Python environments"](./environments.md#using-arbitrary-python-environments). For more, see ["Using arbitrary Python
environments"](./environments.md#using-arbitrary-python-environments).
## Resolution strategy ## Resolution strategy
For a given set of dependency specifiers, it's often the case that there is no single "correct" For a given set of dependency specifiers, it's often the case that there is no single "correct" set
set of packages to install. Instead, there are many valid sets of packages that satisfy the of packages to install. Instead, there are many valid sets of packages that satisfy the specifiers.
specifiers.
Neither `pip` nor uv make any guarantees about the _exact_ set of packages that will be Neither `pip` nor uv make any guarantees about the _exact_ set of packages that will be installed;
installed; only that the resolution will be consistent, deterministic, and compliant with the only that the resolution will be consistent, deterministic, and compliant with the specifiers. As
specifiers. As such, in some cases, `pip` and uv will yield different resolutions; however, both such, in some cases, `pip` and uv will yield different resolutions; however, both resolutions
resolutions _should_ be equally valid. _should_ be equally valid.
For example, consider: For example, consider:
@ -207,9 +212,9 @@ At time of writing, the most recent `starlette` version is `0.37.2`, and the mos
version is `0.110.0`. However, `fastapi==0.110.0` also depends on `starlette`, and introduces an 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`. 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 If a resolver prioritizes including the most recent version of `starlette`, it would need to use an
an older version of `fastapi` that excludes the upper bound on `starlette`. In practice, this older version of `fastapi` that excludes the upper bound on `starlette`. In practice, this requires
requires falling back to `fastapi==0.1.17`: falling back to `fastapi==0.1.17`:
```text ```text
# This file was autogenerated by uv via the following command: # This file was autogenerated by uv via the following command:
@ -263,8 +268,8 @@ typing-extensions==4.10.0
# pydantic-core # pydantic-core
``` ```
When uv resolutions differ from `pip` in undesirable ways, it's often a sign that the specifiers When uv resolutions differ from `pip` in undesirable ways, it's often a sign that the specifiers are
are too loose, and that the user should consider tightening them. For example, in the case of 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`. `starlette` and `fastapi`, the user could require `fastapi>=0.110.0`.
## `pip check` ## `pip check`
@ -272,7 +277,8 @@ are too loose, and that the user should consider tightening them. For example, i
At present, `uv pip check` will surface the following diagnostics: 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 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 `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 isn't installed.
- A package has a dependency on a package that's installed, but at an incompatible version. - 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. - Multiple versions of a package are installed in the virtual environment.
@ -301,40 +307,40 @@ from PyPI and other registries.
However, when a dependency is provided as a direct URL (e.g., `uv pip install https://...`), pip 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. 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: uv, meanwhile, _does_ enforce `--only-binary` for direct URL dependencies, with one exception: given
given `uv pip install https://... --only-binary flask`, uv _will_ build the source distribution at `uv pip install https://... --only-binary flask`, uv _will_ build the source distribution at the
the given URL if it cannot infer the package name ahead of time, since uv can't determine whether given URL if it cannot infer the package name ahead of time, since uv can't determine whether the
the package is "allowed" in such cases without building its metadata. 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 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. provided. For example, `uv pip install -e . --only-binary :all:` is allowed.
## Bytecode compilation ## Bytecode compilation
Unlike pip, uv does not compile `.py` files to `.pyc` files during installation by default (i.e., Unlike pip, uv does not compile `.py` files to `.pyc` files during installation by default (i.e., uv
uv does not create or populate `__pycache__` directories). To enable bytecode compilation does not create or populate `__pycache__` directories). To enable bytecode compilation during
during installs, pass the `--compile-bytecode` flag to `uv pip install` or `uv pip sync`. installs, pass the `--compile-bytecode` flag to `uv pip install` or `uv pip sync`.
## Strictness and spec enforcement ## Strictness and spec enforcement
uv tends to be stricter than `pip`, and will often reject packages that `pip` would install. uv tends to be stricter than `pip`, and will often reject packages that `pip` would install. For
For example, uv omits packages with invalid version specifiers in its metadata, which `pip` example, uv omits packages with invalid version specifiers in its metadata, which `pip` similarly
similarly plans to exclude in a [future release](https://github.com/pypa/pip/issues/12063). 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 In some cases, uv implements lenient behavior for popular packages that are known to have specific
specific spec compliance issues. spec compliance issues.
If uv rejects a package that `pip` would install due to a spec violation, the best course of If uv rejects a package that `pip` would install due to a spec violation, the best course of action
action is to first attempt to install a newer version of the package; and, if that fails, to report is to first attempt to install a newer version of the package; and, if that fails, to report the
the issue to the package maintainer. issue to the package maintainer.
## `pip` command-line options and subcommands ## `pip` command-line options and subcommands
uv does not support the complete set of `pip`'s command-line options and subcommands, although it uv does not support the complete set of `pip`'s command-line options and subcommands, although it
does support a large subset. does support a large subset.
Missing options and subcommands are prioritized based on user demand and the complexity of Missing options and subcommands are prioritized based on user demand and the complexity of the
the implementation, and tend to be tracked in individual issues. For example: implementation, and tend to be tracked in individual issues. For example:
- [`--prefix`](https://github.com/astral-sh/uv/issues/3076) - [`--prefix`](https://github.com/astral-sh/uv/issues/3076)
- [`--trusted-host`](https://github.com/astral-sh/uv/issues/1339) - [`--trusted-host`](https://github.com/astral-sh/uv/issues/1339)
@ -356,8 +362,8 @@ authentication. uv attaches authentication to all requests for hosts with creden
## `egg` support ## `egg` support
uv does not support features that are considered legacy or deprecated in `pip`. For example, uv does not support features that are considered legacy or deprecated in `pip`. For example, uv does
uv does not support `.egg`-style distributions. not support `.egg`-style distributions.
However, uv does have partial support for (1) `.egg-info`-style distributions (which are 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 occasionally found in Docker images and Conda environments) and (2) legacy editable
@ -372,18 +378,18 @@ but will respect any such existing distributions during resolution, list them wi
There are a few small but notable differences in the default behaviors of `pip compile` and There are a few small but notable differences in the default behaviors of `pip compile` and
`pip-tools`. `pip-tools`.
By default, uv does not write the compiled requirements to an output file. Instead, uv requires By default, uv does not write the compiled requirements to an output file. Instead, uv requires that
that the user specify an output file explicitly with the `-o` or `--output-file` option. 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 By default, uv strips extras when outputting the compiled requirements. In other words, uv defaults
`--strip-extras`, while `pip-compile` defaults to `--no-strip-extras`. `pip-compile` is scheduled to to `--strip-extras`, while `pip-compile` defaults to `--no-strip-extras`. `pip-compile` is scheduled
change this default in the next major release (v8.0.0), at which point both tools will default to 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`. `--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 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 `--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`, in the output file, pass the `--emit-index-url` flag to `uv pip compile`. Unlike `pip-compile`, uv
uv will include all index URLs when `--emit-index-url` is passed, including the default index URL. 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 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 `pip-compile`. To include these options in the output file, pass the `--emit-build-options` flag to

51
docs/pip/compile.md
View file

@ -1,10 +1,16 @@
# Locking environments # 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 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 ## 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. 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`: To lock dependencies declared in a `pyproject.toml`:
@ -12,7 +18,8 @@ To lock dependencies declared in a `pyproject.toml`:
uv pip compile pyproject.toml -o requirements.txt 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. 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`: To lock dependencies declared in a `requirements.in`:
@ -26,7 +33,8 @@ To lock dependencies declared in multiple files:
uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt` 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`: uv also supports legacy `setup.py` and `setup.cfg` formats. To lock dependencies declared in a
`setup.py`:
```bash ```bash
uv pip compile setup.py -o requirements.txt uv pip compile setup.py -o requirements.txt
@ -54,7 +62,8 @@ Note extras are not supported with the `requirements.in` format.
## Upgrading requirements ## 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: 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 ```console
$ echo "ruff==0.3.0" > requirements.txt $ echo "ruff==0.3.0" > requirements.txt
@ -74,9 +83,14 @@ To upgrade all dependencies, there is an `--upgrade` flag.
## Syncing an environment ## 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. 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 lockfile. This means that the environment can have dependencies that aren't declared in the lockfile, which isn't great for reproducibility. To ensure the environment exactly matches the lockfile, use `uv pip sync` instead. When installing with `uv pip install`, packages that are already installed will not be removed
unless they conflict with the lockfile. This means that the environment can have dependencies that
aren't declared in the lockfile, which isn't great for reproducibility. To ensure the environment
exactly matches the lockfile, use `uv pip sync` instead.
To sync an environment with a `requirements.txt` file: To sync an environment with a `requirements.txt` file:
@ -92,8 +106,10 @@ uv pip sync pyproject.toml
## Adding constraints ## Adding constraints
Constraints files are `requirements.txt`-like files that only control the _version_ of a requirement that's installed. However, Constraints files are `requirements.txt`-like files that only control the _version_ of a requirement
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. 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 a constraint, define a bound for a package: To define a constraint, define a bound for a package:
@ -111,13 +127,17 @@ Note that multiple constraints can be defined in each file and multiple files ca
## Overriding dependency versions ## Overriding dependency versions
Overrides files are `requirements.txt`-like files that force a specific version of a requirement to be installed, regardless of Overrides files are `requirements.txt`-like files that force a specific version of a requirement to
the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution. 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 While constraints are _additive_, in that they're combined with the requirements of the constituent
_absolute_, in that they completely replace the requirements of the constituent packages. 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. 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: To define an override, define the new requirement for the problematic package:
@ -131,6 +151,7 @@ To use an overrides file:
uv pip compile requirements.in --override overrides.txt uv pip compile requirements.in --override overrides.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. 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. Note that multiple overrides can be defined in each file and multiple files can be used.

17
docs/pip/dependencies.md
View file

@ -1,6 +1,8 @@
# Declaring dependencies # 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. 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` ## Using `pyproject.toml`
@ -26,13 +28,20 @@ cli = [
] ]
``` ```
Each of the keys defines an "extra", which can be installed using the `--extra` and `--all-extras` flags or `package[<extra>]` syntax. See the documentation on [installing packages](./packages.md#installing-packages-from-files) for more details. Each of the keys defines an "extra", which can be installed using the `--extra` and `--all-extras`
flags or `package[<extra>]` 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`. 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` ## 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. 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: To define dependencies in a `requirements.in` file:

88
docs/pip/environments.md
View file

@ -1,6 +1,11 @@
# Python environments # 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. 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 ## Creating a virtual environment
@ -25,13 +30,14 @@ A Python version can be requested:
uv venv --python 3.11 uv venv --python 3.11
``` ```
Note this requires the requested Python version to be available on the system. Note this requires the requested Python version to be available on the system. However, if
However, if available, uv will download Python for you. available, uv will download Python for you. See the [Python version](../concepts/python-versions.md)
See the [Python version](../concepts/python-versions.md) documentation for more details. documentation for more details.
## Using a virtual environment ## Using a virtual environment
When using the default virtual environment name, uv will automatically find and use the virtual environment during subsequent invocations. When using the default virtual environment name, uv will automatically find and use the virtual
environment during subsequent invocations.
```bash ```bash
uv venv uv venv
@ -52,56 +58,58 @@ source .venv/bin/activate
## Using arbitrary Python environments ## Using arbitrary Python environments
Since uv has no dependency on Python, it can install into virtual environments other than Since uv has no dependency on Python, it can install into virtual environments other than its own.
its own. For example, setting `VIRTUAL_ENV=/path/to/venv` will cause uv to install into For example, setting `VIRTUAL_ENV=/path/to/venv` will cause uv to install into `/path/to/venv`,
`/path/to/venv`, regardless of where uv is installed. Note that if `VIRTUAL_ENV` is set to regardless of where uv is installed. Note that if `VIRTUAL_ENV` is set to a directory that is
a directory that is **not** a [PEP 405 compliant](https://peps.python.org/pep-0405/#specification) **not** a [PEP 405 compliant](https://peps.python.org/pep-0405/#specification) virtual environment,
virtual environment, it will be ignored. it will be ignored.
uv can also install into arbitrary, even non-virtual environments, with the `--python` argument 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` provided to `uv pip sync` or `uv pip install`. For example, `uv pip install
will install into the environment linked to the `/path/to/python` interpreter. --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. For convenience, `uv pip install --system` will install into the system Python environment. Using
Using `--system` is roughly equivalent to `uv pip install --python=$(which python)`, `--system` is roughly equivalent to `uv pip install --python=$(which python)`, but note that
but note that executables that are linked to virtual environments will be skipped. executables that are linked to virtual environments will be skipped. Although we generally recommend
Although we generally recommend using virtual environments for dependency management, using virtual environments for dependency management, `--system` is appropriate in continuous
`--system` is appropriate in continuous integration and containerized environments. integration and containerized environments.
The `--system` flag is also used to opt in to mutating system environments. For example, the The `--system` flag is also used to opt in to mutating system environments. For example, the the
the `--python` argument can be used to request a Python version (e.g., `--python 3.12`), and uv will `--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`), search for an interpreter that meets the request. If uv finds a system interpreter (e.g.,
then the `--system` flag is required to allow modification of this non-virtual Python environment. `/usr/lib/python3.12`), then the `--system` flag is required to allow modification of this
Without the `--system` flag, uv will ignore any interpreters that are not in virtual environments. non-virtual Python environment. Without the `--system` flag, uv will ignore any interpreters that
Conversely, when the `--system` flag is provided, uv will ignore any interpreters that _are_ are not in virtual environments. Conversely, when the `--system` flag is provided, uv will ignore
in virtual environments. any interpreters that _are_ in virtual environments.
Installing into system Python across platforms and distributions is notoriously difficult. uv 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 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 Python on Debian prior to Python 3.10 is unsupported due to the [distribution's patching of
of `distutils` (but not `sysconfig`)](https://ffy00.github.io/blog/02-python-debian-and-the-install-locations/). `distutils` (but not
While we always recommend the use of virtual environments, uv considers them to be required in `sysconfig`)](https://ffy00.github.io/blog/02-python-debian-and-the-install-locations/). While we
these non-standard environments. 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 If uv is installed in a Python environment, e.g., with `pip`, it can still be used to modify other
other environments. However, when invoked with `python -m uv`, uv will default to using the parent 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 interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for
general usage. general usage.
uv itself does not depend on Python, but it does need to locate a Python environment to (1) uv itself does not depend on Python, but it does need to locate a Python environment to (1) install
install dependencies into the environment and (2) build source distributions. dependencies into the environment and (2) build source distributions.
## Discovery of Python environments ## Discovery of Python environments
When running a command that mutates an environment such as `uv pip sync` or `uv pip install`, When running a command that mutates an environment such as `uv pip sync` or `uv pip install`, uv
uv will search for a virtual environment in the following order: will search for a virtual environment in the following order:
- An activated virtual environment based on the `VIRTUAL_ENV` environment variable. - An activated virtual environment based on the `VIRTUAL_ENV` environment variable.
- An activated Conda environment based on the `CONDA_PREFIX` 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. - 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 If no virtual environment is found, uv will prompt the user to create one in the current directory
directory via `uv venv`. via `uv venv`.
If the `--system` flag is included, uv will skip virtual environments and search for: If the `--system` flag is included, uv will skip virtual environments and search for:
@ -109,10 +117,12 @@ If the `--system` flag is included, uv will skip virtual environments and search
- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested - On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
version. version.
If a specific Python version is requested, e.g., `--python 3.7`, additional executable names are included: 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 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 environments. _require_ a virtual environment. Instead, it needs a Python toolchain to create ephemeral
See the documentation on [toolchain discovery](../concepts/python-versions.md#discovery-order) for details on discovery. environments. See the documentation on [toolchain
discovery](../concepts/python-versions.md#discovery-order) for details on discovery.

10
docs/pip/index.md
View file

@ -1,6 +1,10 @@
# The pip interface # The pip interface
uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. These commands work directly with the virtual environment, in contrast to uv's primary interfaces where the virtual environment is managed automatically. The `uv pip` interface exposes the speed and functionality of uv to power users and projects that are not ready to transition away from `pip` and `pip-tools`. uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. These
commands work directly with the virtual environment, in contrast to uv's primary interfaces where
the virtual environment is managed automatically. The `uv pip` interface exposes the speed and
functionality of uv to power users and projects that are not ready to transition away from `pip` and
`pip-tools`.
The following sections discuss the basics of using `uv pip`: The following sections discuss the basics of using `uv pip`:
@ -10,4 +14,6 @@ The following sections discuss the basics of using `uv pip`:
- [Declaring package dependencies](./dependencies.md) - [Declaring package dependencies](./dependencies.md)
- [Locking and syncing environments](./compile.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 differences. Consult the [pip-compatibility guide](./compatibility.md) for details. 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
differences. Consult the [pip-compatibility guide](./compatibility.md) for details.

3
docs/pip/inspection.md
View file

@ -32,7 +32,8 @@ Multiple packages can be inspected at once.
## Verifying an environment ## Verifying an environment
It is possible to install packages with conflicting requirements into an environment if installed in multiple steps. 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: To check for conflicts or missing dependencies in the environment:

6
docs/pip/packages.md
View file

@ -57,7 +57,8 @@ uv pip install "git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e61
uv pip install "git+https://github.com/astral-sh/ruff@main" 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. See the [Git authentication](../configuration/authentication.md#git-authentication) documentation
for installation from a private repository.
## Editable packages ## Editable packages
@ -85,7 +86,8 @@ Install from a `requirements.txt` file:
uv pip install -r requirements.txt uv pip install -r requirements.txt
``` ```
See the [`uv pip compile`](./compile.md) documentation for more information on `requirements.txt` files. See the [`uv pip compile`](./compile.md) documentation for more information on `requirements.txt`
files.
Install from a `pyproject.toml` file: Install from a `pyproject.toml` file:

21
docs/platforms.md
View file

@ -7,10 +7,12 @@ uv has Tier 1 support for the following platforms:
- Linux (x86_64) - Linux (x86_64)
- Windows (x86_64) - Windows (x86_64)
uv is continuously built, tested, and developed against its Tier 1 platforms. Inspired by the uv is continuously built, tested, and developed against its Tier 1 platforms. Inspired by the Rust
Rust project, Tier 1 can be thought of as ["guaranteed to work"](https://doc.rust-lang.org/beta/rustc/platform-support.html). 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: 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 (PPC64)
- Linux (PPC64LE) - Linux (PPC64LE)
@ -19,12 +21,13 @@ uv has Tier 2 support (["guaranteed to build"](https://doc.rust-lang.org/beta/ru
- Linux (i686) - Linux (i686)
- Linux (s390x) - Linux (s390x)
uv ships pre-built wheels to [PyPI](https://pypi.org/project/uv/) for its Tier 1 and uv ships pre-built wheels to [PyPI](https://pypi.org/project/uv/) for its Tier 1 and Tier 2
Tier 2 platforms. However, while Tier 2 platforms are continuously built, they are not continuously platforms. However, while Tier 2 platforms are continuously built, they are not continuously tested
tested or developed against, and so stability may vary in practice. 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_ Beyond the Tier 1 and Tier 2 platforms, uv is known to build on i686 Windows, and known _not_ to
to build on aarch64 Windows, but does not consider either platform to be supported at this time. build on aarch64 Windows, but does not consider either platform to be supported at this time. The
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). 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. uv supports and is tested against Python 3.8, 3.9, 3.10, 3.11, and 3.12.