mirrors/uv
1
0
Fork 0
mirror of https://github.com/astral-sh/uv.git synced 2025-11-02 04:48:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Use prettier to format the documentation (#5708)

Browse source 
To enforce the 100 character line limit in markdown files introduced in
https://github.com/astral-sh/uv/pull/5635, and to automate the
formatting of markdown files, i've added prettier and formatted our
markdown files with it.

I've excluded the changelog and the generated references documentation
from this for having too many changes, but we can also include them.

I'm not particular on which style we use. My main motivations are
(major) not having to reflow markdown files myself anymore and (minor)
consistence between all markdown files. I've chosen prettier for similar
reason as we chose black, it's a single good style that's automated and
shared in the community. I do prefer prettier's style of not breaking
inside of a link name though.

This PR is in two parts, the first adds prettier to CI and documents
using it, while the second actually formats the docs. When merge
conflicts arise, we can drop the last commit and regenerate it with `npx
prettier --prose-wrap always --write BENCHMARKS.md CONTRIBUTING.md
README.md STYLE.md docs/*.md docs/concepts/**/*.md docs/guides/**/*.md
docs/pip/**/*.md`.

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
This commit is contained in:
konsti 2024-08-02 15:58:31 +02:00 • committed by GitHub
parent f2c4b9c752
commit db371560bc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
42 changed files with 711 additions and 646 deletions
Download patch file Download diff file Expand all files Collapse all files

4
.github/workflows/ci.yml vendored
View file

@ -57,7 +57,9 @@ jobs:
run: cargo fmt --all --check run: cargo fmt --all --check
- name: "Prettier" - name: "Prettier"
run: npx prettier --check "**/*.{json5,yaml,yml}" run: |
npx prettier --check "**/*.{json5,yaml,yml}"
npx prettier --prose-wrap always --check "**/*.md"
- name: "README check" - name: "README check"
run: python scripts/transform_readme.py --target pypi run: python scripts/transform_readme.py --target pypi

4
.prettierignore Normal file
View file

@ -0,0 +1,4 @@
.venv
CHANGELOG.md
PREVIEW-CHANGELOG.md
docs/reference/*.md

55
BENCHMARKS.md
View file

@ -3,17 +3,17 @@
All benchmarks were computed on macOS using Python 3.12.0 (for non-uv tools), and come with a few All benchmarks were computed on macOS using Python 3.12.0 (for non-uv tools), and come with a few
important caveats: important caveats:
- Benchmark performance may vary dramatically across different operating systems and filesystems. - Benchmark performance may vary dramatically across different operating systems and filesystems. In
In particular, uv uses different installation strategies based on the underlying filesystem's particular, uv uses different installation strategies based on the underlying filesystem's
capabilities. (For example, uv uses reflinking on macOS, and hardlinking on Linux.) capabilities. (For example, uv uses reflinking on macOS, and hardlinking on Linux.)
- Benchmark performance may vary dramatically depending on the set of packages being installed. - Benchmark performance may vary dramatically depending on the set of packages being installed. For
For example, a resolution that requires building a single intensive source distribution may appear example, a resolution that requires building a single intensive source distribution may appear
very similar across tools, since the bottleneck is tool-agnostic. very similar across tools, since the bottleneck is tool-agnostic.
- Unlike Poetry, both uv and pip-tools do _not_ generate multi-platform lockfiles. As such, - Unlike Poetry, both uv and pip-tools do _not_ generate multi-platform lockfiles. As such, Poetry
Poetry is (by design) doing significantly more work than other tools in the resolution benchmarks. is (by design) doing significantly more work than other tools in the resolution benchmarks. Poetry
Poetry is included for completeness, as many projects may not _need_ a multi-platform lockfile. is included for completeness, as many projects may not _need_ a multi-platform lockfile. However,
However, it's critical to understand that benchmarking uv's resolution time against Poetry is it's critical to understand that benchmarking uv's resolution time against Poetry is an unfair
an unfair comparison. (Benchmarking installation, however, _is_ a fair comparison.) comparison. (Benchmarking installation, however, _is_ a fair comparison.)
This document benchmarks against Trio's `docs-requirements.in`, as a representative example of a This document benchmarks against Trio's `docs-requirements.in`, as a representative example of a
real-world project. real-world project.
@ -22,17 +22,17 @@ In each case, a smaller bar (i.e., lower) is better.
## Warm Installation ## Warm Installation
Benchmarking package installation (e.g., `uv pip sync`) with a warm cache. This is equivalent Benchmarking package installation (e.g., `uv pip sync`) with a warm cache. This is equivalent to
to removing and recreating a virtual environment, and then populating it with dependencies that removing and recreating a virtual environment, and then populating it with dependencies that you've
you've installed previously on the same machine. installed previously on the same machine.
![install-warm](./assets/png/install-warm.png) ![install-warm](./assets/png/install-warm.png)
## Cold Installation ## Cold Installation
Benchmarking package installation (e.g., `uv pip sync`) with a cold cache. This is equivalent Benchmarking package installation (e.g., `uv pip sync`) with a cold cache. This is equivalent to
to running `uv pip sync` on a new machine or in CI (assuming that the package manager cache is running `uv pip sync` on a new machine or in CI (assuming that the package manager cache is not
not shared across runs). shared across runs).
![install-cold](./assets/png/install-cold.png) ![install-cold](./assets/png/install-cold.png)
@ -46,23 +46,24 @@ from a `requirements.in` file.
## Cold Resolution ## Cold Resolution
Benchmarking dependency resolution (e.g., `uv pip compile`) with a cold cache. This is Benchmarking dependency resolution (e.g., `uv pip compile`) with a cold cache. This is equivalent to
equivalent to running `uv pip compile` on a new machine or in CI (assuming that the package running `uv pip compile` on a new machine or in CI (assuming that the package manager cache is not
manager cache is not shared across runs). shared across runs).
![resolve-cold](./assets/png/resolve-cold.png) ![resolve-cold](./assets/png/resolve-cold.png)
## Reproduction ## Reproduction
All benchmarks were generated using the `scripts/benchmark` package, which wraps All benchmarks were generated using the `scripts/benchmark` package, which wraps
[`hyperfine`](https://github.com/sharkdp/hyperfine) to facilitate benchmarking uv [`hyperfine`](https://github.com/sharkdp/hyperfine) to facilitate benchmarking uv against a variety
against a variety of other tools. of other tools.
The benchmark script itself has a several requirements: The benchmark script itself has a several requirements:
- A local uv release build (`cargo build --release`). - A local uv release build (`cargo build --release`).
- An installation of the production `uv` binary in your path. - An installation of the production `uv` binary in your path.
- The [`hyperfine`](https://github.com/sharkdp/hyperfine) command-line tool installed on your system. - The [`hyperfine`](https://github.com/sharkdp/hyperfine) command-line tool installed on your
system.
To benchmark resolution against pip-compile, Poetry, and PDM: To benchmark resolution against pip-compile, Poetry, and PDM:
@ -101,15 +102,21 @@ cargo run -p uv-dev render-benchmarks install-warm.json --title "Warm Installati
cargo run -p uv-dev render-benchmarks install-cold.json --title "Cold Installation" cargo run -p uv-dev render-benchmarks install-cold.json --title "Cold Installation"
``` ```
You need to install the [Roboto Font](https://fonts.google.com/specimen/Roboto) if the labels are missing in the generated graph. You need to install the [Roboto Font](https://fonts.google.com/specimen/Roboto) if the labels are
missing in the generated graph.
## Acknowledgements ## Acknowledgements
The inclusion of this `BENCHMARKS.md` file was inspired by the excellent benchmarking documentation The inclusion of this `BENCHMARKS.md` file was inspired by the excellent benchmarking documentation
in [Orogene](https://github.com/orogene/orogene/blob/472e481b4fc6e97c2b57e69240bf8fe995dfab83/BENCHMARKS.md). in
[Orogene](https://github.com/orogene/orogene/blob/472e481b4fc6e97c2b57e69240bf8fe995dfab83/BENCHMARKS.md).
## Troubleshooting ## Troubleshooting
### Flaky benchmarks ### Flaky benchmarks
If you're seeing high variance when running the cold benchmarks, then it's likely that you're running into throttling or DDoS prevention from your ISP. In that case, ISPs forcefully terminate TCP connections with a TCP reset. We believe this is due to the benchmarks making the exact same requests in a very short time (especially true for `uv`). A possible workaround is to connect to VPN to bypass your ISPs filtering mechanism. If you're seeing high variance when running the cold benchmarks, then it's likely that you're
running into throttling or DDoS prevention from your ISP. In that case, ISPs forcefully terminate
TCP connections with a TCP reset. We believe this is due to the benchmarks making the exact same
requests in a very short time (especially true for `uv`). A possible workaround is to connect to VPN
to bypass your ISPs filtering mechanism.

1
CHANGELOG.md
View file

@ -1755,3 +1755,4 @@ pass the `--native-tls` command-line flag to enable this behavior.
- Fix diagram alignment ([#1354](https://github.com/astral-sh/uv/pull/1354)) - Fix diagram alignment ([#1354](https://github.com/astral-sh/uv/pull/1354))
- Grammar nit ([#1345](https://github.com/astral-sh/uv/pull/1345)) - Grammar nit ([#1345](https://github.com/astral-sh/uv/pull/1345))
<!-- prettier-ignore-end -->

86
CONTRIBUTING.md
View file

@ -1,9 +1,9 @@
# Contributing # Contributing
We have issues labeled as [Good First We have issues labeled as
Issue](https://github.com/astral-sh/uv/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) [Good First Issue](https://github.com/astral-sh/uv/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
and [Help and
Wanted](https://github.com/astral-sh/uv/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) [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. which are good opportunities for new contributors.
## Setup ## Setup
@ -30,8 +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 You can install CMake from the [installers](https://cmake.org/download/) or with
cmake`. `pipx install cmake`.
## Testing ## Testing
@ -62,9 +62,9 @@ cargo run -- pip install requests
When testing debug builds on Windows, the stack can overflow resulting in a `STATUS_STACK_OVERFLOW` When testing debug builds on Windows, the stack can overflow resulting in a `STATUS_STACK_OVERFLOW`
error code. This is due to a small stack size limit on Windows that we encounter when running error code. This is due to a small stack size limit on Windows that we encounter when running
unoptimized builds — the release builds do not have this problem. We [added a `UV_STACK_SIZE` unoptimized builds — the release builds do not have this problem. We
variable](https://github.com/astral-sh/uv/pull/941) to bypass this problem during testing. We [added a `UV_STACK_SIZE` variable](https://github.com/astral-sh/uv/pull/941) to bypass this problem
recommend bumping the stack size from the default of 1MB to 2MB, for example: 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'
@ -73,8 +73,8 @@ $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 Source distributions can run arbitrary code on build and can make unwanted modifications to your
system (["Someone's Been Messing With My Subnormals!" on system
Blogspot](https://moyix.blogspot.com/2022/09/someones-been-messing-with-my-subnormals.html), (["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 ["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: just resolving requirements. To prevent this, there's a Docker container you can run commands in:
@ -90,9 +90,9 @@ trying to resolve or install.
## Profiling and Benchmarking ## Profiling and Benchmarking
Please refer to Ruff's [Profiling Please refer to Ruff's
Guide](https://github.com/astral-sh/ruff/blob/main/CONTRIBUTING.md#profiling-projects), it applies [Profiling Guide](https://github.com/astral-sh/ruff/blob/main/CONTRIBUTING.md#profiling-projects),
to uv, too. it applies to uv, too.
We provide diverse sets of requirements for testing and benchmarking the resolver in We provide diverse sets of requirements for testing and benchmarking the resolver in
`scripts/requirements` and for the installer in `scripts/requirements/compiled`. `scripts/requirements` and for the installer in `scripts/requirements/compiled`.
@ -141,35 +141,35 @@ To preview any changes to the documentation locally:
1. Install MkDocs and Material for MkDocs with: 1. Install MkDocs and Material for MkDocs with:
```shell ```shell
uv venv uv venv
# For contributors. # For contributors.
uv pip install -r docs/requirements.txt uv pip install -r docs/requirements.txt
# Or, for members of the Astral org, which has access to MkDocs Insiders via sponsorship. # Or, for members of the Astral org, which has access to MkDocs Insiders via sponsorship.
uv pip install -r docs/requirements-insiders.txt uv pip install -r docs/requirements-insiders.txt
``` ```
1. Activate the virtual environment with: 1. Activate the virtual environment with:
```shell ```shell
# On macOS and Linux. # On macOS and Linux.
source .venv/bin/activate source .venv/bin/activate
# On Windows. # On Windows.
.venv\Scripts\activate .venv\Scripts\activate
``` ```
1. Run the development server with: 1. Run the development server with:
```shell ```shell
# For contributors. # For contributors.
mkdocs serve -f mkdocs.public.yml mkdocs serve -f mkdocs.public.yml
# For members of the Astral org, which has access to MkDocs Insiders via sponsorship. # For members of the Astral org, which has access to MkDocs Insiders via sponsorship.
mkdocs serve -f mkdocs.insiders.yml mkdocs serve -f mkdocs.insiders.yml
``` ```
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/).
@ -182,9 +182,15 @@ 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 is deployed automatically on release by publishing to the
documentation](https://github.com/astral-sh/docs) repository, which itself deploys via Cloudflare [Astral documentation](https://github.com/astral-sh/docs) repository, which itself deploys via
Pages. Cloudflare Pages.
After making changes to the documentation, format the markdown files with:
```shell
npx prettier --prose-wrap always --write "**/*.md"
```
## Releases ## Releases
@ -202,7 +208,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 After merging the pull request, run the
workflow](https://github.com/astral-sh/uv/actions/workflows/release.yml) with the version tag. **Do [release workflow](https://github.com/astral-sh/uv/actions/workflows/release.yml) with the version
not include a leading `v`**. The release will automatically be created on GitHub after everything tag. **Do not include a leading `v`**. The release will automatically be created on GitHub after
else publishes. everything else publishes.

203
PIP_COMPATIBILITY.md
View file

@ -6,9 +6,9 @@ Informally, the intent is such that existing `pip` and `pip-tools` users can swi
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 install` for `uv pip install` should "just work". `pip install` for `uv pip install` should "just work".
However, uv is _not_ intended to be an _exact_ clone of `pip`, and the further you stray from 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,27 +46,30 @@ 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
to model, and are a frequent source of bugs in packaging tools. Even `pip`, which is viewed as a [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to
reference implementation, has a number of open questions around pre-release handling ([#12469](https://github.com/pypa/pip/issues/12469), model, and are a frequent source of bugs in packaging tools. Even `pip`, which is viewed as a
[#12470](https://github.com/pypa/pip/issues/12470), [#40505](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/20), etc.). reference implementation, has a number of open questions around pre-release handling
([#12469](https://github.com/pypa/pip/issues/12469),
[#12470](https://github.com/pypa/pip/issues/12470),
[#40505](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/20), etc.).
uv's pre-release handling is _intentionally_ limited and _intentionally_ requires user opt-in for 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
cover "dependency resolution"](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/17) [do not cover "dependency resolution"](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/17)
and are instead focused on behavior for a _single_ version specifier. As such, there are unresolved 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 +82,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 +105,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,58 +115,64 @@ 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
in which it searches indexes, and expects that packages are unique up to name and version, even [no guarantees around the order](https://github.com/pypa/pip/issues/5045#issuecomment-369521345) in
across indexes. which it searches indexes, and expects that packages are unique up to name and version, even across
indexes.
uv's behavior is such that if a package exists on an internal index, it should always be installed 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,
from December 2022. [the `torchtriton` attack](https://pytorch.org/blog/compromised-nightly-dependency/) from
December 2022.
As of v0.1.39, users can opt in to `pip`-style behavior for multiple indexes via the 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,
address the "dependency confusion" issue across package registries and installers. [PEP 708](https://peps.python.org/pep-0708/) is a provisional standard that aims to address the
"dependency confusion" issue across package registries and installers.
## PEP 517 build isolation ## PEP 517 build isolation
uv uses [PEP 517](https://peps.python.org/pep-0517/) build isolation by default (akin to `pip install --use-pep517`), uv uses [PEP 517](https://peps.python.org/pep-0517/) build isolation by default (akin to
following `pypa/build` and in anticipation of `pip` defaulting to PEP 517 builds in the future ([pypa/pip#9175](https://github.com/pypa/pip/issues/9175)). `pip install --use-pep517`), following `pypa/build` and in anticipation of `pip` defaulting to PEP
517 builds in the future ([pypa/pip#9175](https://github.com/pypa/pip/issues/9175)).
If a package fails to install due to a missing build-time dependency, try using a newer version of the package; if the If a package fails to install due to a missing build-time dependency, try using a newer version of
problem persists, consider filing an issue with the package maintainer, requesting that they update the packaging setup the package; if the problem persists, consider filing an issue with the package maintainer,
to declare the correct PEP 517 build-time dependencies. requesting that they update the packaging setup to declare the correct PEP 517 build-time
dependencies.
As an escape hatch, you can preinstall a package's build dependencies, then run `uv pip install` with As an escape hatch, you can preinstall a package's build dependencies, then run `uv pip install`
`--no-build-isolation`, as in: with `--no-build-isolation`, as in:
```shell ```shell
uv pip install wheel && uv pip install --no-build-isolation biopython==1.77 uv pip install wheel && uv pip install --no-build-isolation biopython==1.77
``` ```
For a list of packages that are known to fail under PEP 517 build isolation, see [#2252](https://github.com/astral-sh/uv/issues/2252). For a list of packages that are known to fail under PEP 517 build isolation, see
[#2252](https://github.com/astral-sh/uv/issues/2252).
## Transitive direct URL dependencies for constraints and overrides ## Transitive direct URL dependencies for constraints and overrides
@ -193,26 +202,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 ["Installing into arbitrary Python environments"](./README.md#installing-into-arbitrary-python-environments). For more, see
["Installing into arbitrary Python environments"](./README.md#installing-into-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:
@ -225,9 +234,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:
@ -281,8 +290,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`
@ -290,7 +299,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.
@ -319,40 +329,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:
- [`--trusted-host`](https://github.com/astral-sh/uv/issues/1339) - [`--trusted-host`](https://github.com/astral-sh/uv/issues/1339)
- [`--user`](https://github.com/astral-sh/uv/issues/2077) - [`--user`](https://github.com/astral-sh/uv/issues/2077)
@ -373,8 +383,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
@ -387,8 +397,8 @@ but will respect any such existing distributions during resolution, list them wi
## Build constraints ## Build constraints
When constraints are provided via `--constraint` (or `UV_CONSTRAINT`), uv will _not_ apply the When constraints are provided via `--constraint` (or `UV_CONSTRAINT`), uv will _not_ apply the
constraints when resolving build dependencies (i.e., to build a source distribution). Instead, constraints when resolving build dependencies (i.e., to build a source distribution). Instead, build
build constraints should be provided via the dedicated `--build-constraint` (or `UV_BUILD_CONSTRAINT`) constraints should be provided via the dedicated `--build-constraint` (or `UV_BUILD_CONSTRAINT`)
setting. setting.
pip, meanwhile, applies constraints to build dependencies when specified via `PIP_CONSTRAINT`, but pip, meanwhile, applies constraints to build dependencies when specified via `PIP_CONSTRAINT`, but
@ -402,18 +412,18 @@ dependency on `setuptools`, use `--build-constraint`, rather than `--constraint`
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.
## `requires-python` enforcement ## `requires-python` enforcement
@ -425,5 +435,6 @@ For example, a project that declares `requires-python: >=3.13` will accept Pytho
3.13.0b1 is not strictly greater than 3.13, it is greater than 3.13 when the pre-release identifier 3.13.0b1 is not strictly greater than 3.13, it is greater than 3.13 when the pre-release identifier
is omitted. is omitted.
While this is not strictly compliant with [PEP 440](https://peps.python.org/pep-0440/), While this is not strictly compliant with [PEP 440](https://peps.python.org/pep-0440/), it _is_
it _is_ consistent with [pip](https://github.com/pypa/pip/blob/24.1.1/src/pip/_internal/resolution/resolvelib/candidates.py#L540). consistent with
[pip](https://github.com/pypa/pip/blob/24.1.1/src/pip/_internal/resolution/resolvelib/candidates.py#L540).

334
README.md
View file

@ -25,21 +25,22 @@ replacement for common `pip` and `pip-tools` workflows.
## Highlights ## Highlights
- ⚖️ Drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. - ⚖️ Drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands.
- ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip` - ⚡️ [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 for dependency deduplication. - 💾 Disk-space efficient, with a global cache for dependency deduplication.
- 🐍 Installable via `curl`, `pip`, `pipx`, etc. uv is a static binary that can be installed - 🐍 Installable via `curl`, `pip`, `pipx`, etc. uv is a static binary that can be installed without
without Rust or Python. Rust or Python.
- 🧪 Tested at-scale against the top 10,000 PyPI packages. - 🧪 Tested at-scale against the top 10,000 PyPI packages.
- 🖥️ Support for macOS, Linux, and Windows. - 🖥️ Support for macOS, Linux, and Windows.
- 🧰 Advanced features such as [dependency version overrides](#dependency-overrides) and - 🧰 Advanced features such as [dependency version overrides](#dependency-overrides) and
[alternative resolution strategies](#resolution-strategy). [alternative resolution strategies](#resolution-strategy).
- ⁉️ Best-in-class error messages with a conflict-tracking resolver. - ⁉️ Best-in-class error messages with a conflict-tracking resolver.
- 🤝 Support for a wide range of advanced `pip` features, including editable installs, Git - 🤝 Support for a wide range of advanced `pip` features, including editable installs, Git
dependencies, direct URL dependencies, local dependencies, constraints, source distributions, dependencies, direct URL dependencies, local dependencies, constraints, source distributions, HTML
HTML and JSON indexes, and more. and JSON indexes, and more.
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
@ -108,8 +109,8 @@ To sync a set of locked dependencies with the virtual environment:
uv pip sync requirements.txt # Install from a requirements.txt file. uv pip sync requirements.txt # Install from a requirements.txt file.
``` ```
uv's `pip-install` and `pip-compile` commands support many of the same command-line arguments uv's `pip-install` and `pip-compile` commands support many of the same command-line arguments as
as existing tools, including `-r requirements.txt`, `-c constraints.txt`, `-e .` (for editable existing tools, including `-r requirements.txt`, `-c constraints.txt`, `-e .` (for editable
installs), `--index-url`, and more. installs), `--index-url`, and more.
## Limitations ## Limitations
@ -120,17 +121,18 @@ development.
For details, see our [`pip` compatibility guide](./PIP_COMPATIBILITY.md). For details, see our [`pip` compatibility guide](./PIP_COMPATIBILITY.md).
Like `pip-compile`, uv generates a platform-specific `requirements.txt` file (unlike, e.g., Like `pip-compile`, uv generates a platform-specific `requirements.txt` file (unlike, e.g., `poetry`
`poetry` and `pdm`, which generate platform-agnostic `poetry.lock` and `pdm.lock` files). As such, and `pdm`, which generate platform-agnostic `poetry.lock` and `pdm.lock` files). As such, uv's
uv's `requirements.txt` files may not be portable across platforms and Python versions. `requirements.txt` files may not be portable across platforms and Python versions.
## Roadmap ## Roadmap
uv is an extremely fast Python package resolver and installer, designed as a drop-in uv is an extremely fast Python package resolver and installer, designed as a drop-in replacement for
replacement for `pip`, `pip-tools` (`pip-compile` and `pip-sync`), and `virtualenv`. `pip`, `pip-tools` (`pip-compile` and `pip-sync`), and `virtualenv`.
uv represents an intermediary goal in our pursuit of a ["Cargo for Python"](https://blog.rust-lang.org/2016/05/05/cargo-pillars.html#pillars-of-cargo): uv represents an intermediary goal in our pursuit of a
a comprehensive project and package manager that is extremely fast, reliable, and easy to use. ["Cargo for Python"](https://blog.rust-lang.org/2016/05/05/cargo-pillars.html#pillars-of-cargo): a
comprehensive project and package manager that is extremely fast, reliable, and easy to use.
Think: a single binary that bootstraps your Python installation and gives you everything you need to Think: a single binary that bootstraps your Python installation and gives you everything you need to
be productive with Python, bundling not only `pip`, `pip-tools`, and `virtualenv`, but also `pipx`, be productive with Python, bundling not only `pip`, `pip-tools`, and `virtualenv`, but also `pipx`,
@ -146,29 +148,29 @@ useful with a minimal barrier to adoption.
### Python discovery ### Python discovery
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.
When running `pip sync` or `pip install`, uv will search for a virtual environment in the When running `pip sync` or `pip install`, uv will search for a virtual environment in the following
following order: 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`.
When running `pip compile`, uv does not _require_ a virtual environment and will search for a When running `pip compile`, uv does not _require_ a virtual environment and will search for a Python
Python interpreter in the following order: interpreter 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.
- The Python interpreter available as `python3` on macOS and Linux, or `python.exe` on Windows. - The Python interpreter available as `python3` on macOS and Linux, or `python.exe` on Windows.
If a `--python-version` is provided to `pip compile` (e.g., `--python-version=3.7`), uv will If a `--python-version` is provided to `pip compile` (e.g., `--python-version=3.7`), uv will search
search for a Python interpreter matching that version in the following order: for a Python interpreter matching that version 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.
@ -180,39 +182,40 @@ search for a Python interpreter matching that version in the following order:
### Installing into arbitrary Python environments ### Installing into 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,
will install into the environment linked to the `/path/to/python` interpreter. `uv pip install --python=/path/to/python` will install into the environment linked to the
`/path/to/python` interpreter.
For convenience, `uv pip install --system` will install into the system Python environment. 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
`--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
of `distutils` (but not `sysconfig`)](https://ffy00.github.io/blog/02-python-debian-and-the-install-locations/). [distribution's patching of `distutils` (but not `sysconfig`)](https://ffy00.github.io/blog/02-python-debian-and-the-install-locations/).
While we always recommend the use of virtual environments, uv considers them to be required in While we always recommend the use of virtual environments, uv considers them to be required in these
these non-standard environments. 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.
@ -223,16 +226,16 @@ uv supports persistent configuration at both the project- and user-level.
Specifically, uv will search for a `pyproject.toml` or `uv.toml` file in the current directory, or 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 ```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:
@ -264,25 +267,31 @@ configuration files (e.g., user-level configuration will be ignored).
### 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, uv will query the [Git credential helper](https://git-scm.com/doc/credential-helpers). If there are no credentials present in the URL and authentication is needed, uv will query the
[Git credential helper](https://git-scm.com/doc/credential-helpers).
### HTTP authentication ### HTTP authentication
@ -294,12 +303,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:
@ -308,19 +317,19 @@ 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`.
### 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 compile` will pin Git dependencies to a specific commit hash when writing the resolved `uv pip compile` will pin Git dependencies to a specific commit hash when writing the resolved
dependency set. dependency set.
@ -340,19 +349,20 @@ 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 ...`.
- To clear the global cache entirely, run `uv cache clean`. - To clear the global cache entirely, run `uv cache clean`.
### 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
@ -412,36 +422,38 @@ 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
to model, and are a frequent source of bugs in other packaging tools. uv's pre-release handling [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to
is _intentionally_ limited and _intentionally_ requires user opt-in for pre-releases, to ensure model, and are a frequent source of bugs in other packaging tools. uv's pre-release handling is
_intentionally_ limited and _intentionally_ requires user opt-in for pre-releases, to ensure
correctness. 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
@ -449,8 +461,8 @@ 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. Unlike Poetry and PDM, uv does not yet produce a current platform and Python version. Unlike Poetry and PDM, uv does not yet produce a
machine-agnostic lockfile ([#2679](https://github.com/astral-sh/uv/issues/2679)). machine-agnostic lockfile ([#2679](https://github.com/astral-sh/uv/issues/2679)).
However, uv _does_ support resolving for alternate platforms and Python versions via the However, uv _does_ support resolving for alternate platforms and Python versions via the
@ -464,28 +476,30 @@ Similarly, if you're running uv on Python 3.9, but want to resolve for Python 3.
`uv pip compile --python-version=3.8 requirements.in` to produce a Python 3.8-compatible resolution. `uv pip compile --python-version=3.8 requirements.in` to produce a Python 3.8-compatible resolution.
The `--python-platform` and `--python-version` arguments can be combined to produce a resolution for 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.
_N.B. Python's environment markers expose far more information about the current machine _N.B. Python's environment markers expose far more information about the current machine than can be
than can be expressed by a simple `--python-platform` argument. For example, the `platform_version` marker expressed by a simple `--python-platform` argument. For example, the `platform_version` marker on
on macOS includes the time at which the kernel was built, which can (in theory) be encoded in macOS includes the time at which the kernel was built, which can (in theory) be encoded in package
package requirements. uv's resolver makes a best-effort attempt to generate a resolution that is requirements. uv's resolver makes a best-effort attempt to generate a resolution that is compatible
compatible with any machine running on the target `--python-platform`, which should be sufficient for with any machine running on the target `--python-platform`, which should be sufficient for most use
most use cases, but may lose fidelity for complex package and platform combinations._ cases, but may lose fidelity for complex package and platform combinations._
### 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
If the field is not present for a given distribution, the distribution will be treated as unavailable. [`PEP 700`](https://peps.python.org/pep-0700/). If the field is not present for a given
distribution, the distribution will be treated as unavailable.
To ensure reproducibility, messages for unsatisfiable resolutions will not mention that distributions were excluded 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.
### Custom CA certificates ### Custom CA certificates
@ -503,7 +517,8 @@ 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.
## Platform support ## Platform support
@ -514,10 +529,13 @@ 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)
@ -526,13 +544,14 @@ 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.
@ -542,8 +561,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
@ -552,34 +571,33 @@ 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_BUILD_CONSTRAINT`: Equivalent to the `--build-constraint` command-line argument. If set, uv - `UV_BUILD_CONSTRAINT`: Equivalent to the `--build-constraint` command-line argument. If set, uv
will use this file as constraints for any source distribution builds. Uses space-separated list of files. will use this file as constraints for any source distribution builds. Uses space-separated list of
- `UV_OVERRIDE`: Equivalent to the `--override` command-line argument. If set, uv will use this files.
file as the overrides file. Uses space-separated list of files. - `UV_OVERRIDE`: Equivalent to the `--override` command-line argument. If set, uv will use this file
- `UV_LINK_MODE`: Equivalent to the `--link-mode` command-line argument. If set, uv will use this as the overrides file. Uses space-separated list of files.
as a link mode. - `UV_LINK_MODE`: Equivalent to the `--link-mode` command-line argument. If set, uv will use this as
a link mode.
- `UV_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` command-line argument. If set, - `UV_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`
@ -611,13 +629,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).
@ -628,8 +647,10 @@ 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).
## Versioning ## Versioning
@ -641,30 +662,31 @@ adhere to [Semantic Versioning](https://semver.org/).
## Acknowledgements ## Acknowledgements
uv's dependency resolver uses [PubGrub](https://github.com/pubgrub-rs/pubgrub) under the hood. uv's dependency resolver uses [PubGrub](https://github.com/pubgrub-rs/pubgrub) under the hood. We're
We're grateful to the PubGrub maintainers, especially [Jacob Finkelman](https://github.com/Eh2406), grateful to the PubGrub maintainers, especially [Jacob Finkelman](https://github.com/Eh2406), for
for their support. their support.
uv's Git implementation is based on [Cargo](https://github.com/rust-lang/cargo). uv's Git implementation is based on [Cargo](https://github.com/rust-lang/cargo).
Some of uv's optimizations are inspired by the great work we've seen in Some of uv's optimizations are inspired by the great work we've seen in [pnpm](https://pnpm.io/),
[pnpm](https://pnpm.io/), [Orogene](https://github.com/orogene/orogene), and [Orogene](https://github.com/orogene/orogene), and [Bun](https://github.com/oven-sh/bun). We've also
[Bun](https://github.com/oven-sh/bun). We've also learned a lot from Nathaniel learned a lot from Nathaniel J. Smith's [Posy](https://github.com/njsmith/posy) and adapted its
J. Smith's [Posy](https://github.com/njsmith/posy) and adapted its [trampoline](https://github.com/njsmith/posy/tree/main/src/trampolines/windows-trampolines/posy-trampoline) [trampoline](https://github.com/njsmith/posy/tree/main/src/trampolines/windows-trampolines/posy-trampoline)
for Windows support. for Windows support.
## License ## License
uv is licensed under either of uv is licensed under either of
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0) - Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
https://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) - MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
at your option. at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in uv
for inclusion in uv by you, as defined in the Apache-2.0 license, shall be by you, as defined in the Apache-2.0 license, shall be dually licensed as above, without any
dually licensed as above, without any additional terms or conditions. additional terms or conditions.
<div align="center"> <div align="center">
<a target="_blank" href="https://astral.sh" style="background:none"> <a target="_blank" href="https://astral.sh" style="background:none">

29
STYLE.md
View file

@ -13,11 +13,11 @@ documentation_.
1. Use less than and greater than symbols to wrap bare URLs, e.g., `<https://astral.sh>` (unless it 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). 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 1. If a message ends with a single relevant value, precede it with a colon, e.g.,
value: value`. If the value is a literal, wrap it in backticks. `This is the value: value`. If the value is a literal, wrap it in backticks.
1. Markdown files should be wrapped at 100 characters. 1. Markdown files should be wrapped at 100 characters.
1. Use a space, not an equals sign, for command line arguments with a value, e.g. 1. Use a space, not an equals sign, for command line arguments with a value, e.g.
`--resolution lowest`, not `--resolution=lowest`. `--resolution lowest`, not `--resolution=lowest`.
## Styling uv ## Styling uv
@ -30,7 +30,8 @@ Just uv, please.
## Terminology ## Terminology
1. Use "lockfile" not "lock file". 1. Use "lockfile" not "lock file".
2. Use "pre-release", not "prerelease" (except in code, in which case: use `Prerelease`, not `PreRelease`; and `prerelease`, not `pre_release`). 2. Use "pre-release", not "prerelease" (except in code, in which case: use `Prerelease`, not
`PreRelease`; and `prerelease`, not `pre_release`).
## Documentation ## Documentation
@ -100,18 +101,18 @@ The documentation is divided into:
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:
- Green for success. - Green for success.
- Red for error. - Red for error.
- Yellow for warning. - Yellow for warning.
- Cyan for hints. - Cyan for hints.
- Cyan for file paths. - Cyan for file paths.
- Cyan for important user-facing literals (e.g., a package name in a message). - Cyan for important user-facing literals (e.g., a package name in a message).
- Green for commands. - Green for commands.
### Logging ### Logging
1. `warn`, `info`, `debug`, and `trace` logs are all shown with the `--verbose` flag. 1. `warn`, `info`, `debug`, and `trace` logs are all shown with the `--verbose` flag.
- Note that the displayed level is controlled with `RUST_LOG`. - Note that the displayed level is controlled with `RUST_LOG`.
1. All logging should be to stderr. 1. All logging should be to stderr.
### Output ### Output
@ -121,8 +122,8 @@ The documentation is divided into:
### Warnings ### Warnings
1. `warn_user` and `warn_user_once` are shown without the `--verbose `flag. 1. `warn_user` and `warn_user_once` are shown without the `--verbose `flag.
- These methods should be preferred over tracing warnings when the warning is actionable. - These methods should be preferred over tracing warnings when the warning is actionable.
- Deprecation warnings should use these methods. - Deprecation warnings should use these methods.
1. Deprecation warnings must be actionable. 1. Deprecation warnings must be actionable.
### Hints ### Hints

7
crates/README.md
View file

@ -41,7 +41,8 @@ Functionality for detecting the current platform (operating system, architecture
## [platform-tags](./platform-tags) ## [platform-tags](./platform-tags)
Functionality for parsing and inferring Python platform tags as per [PEP 425](https://peps.python.org/pep-0425/). Functionality for parsing and inferring Python platform tags as per
[PEP 425](https://peps.python.org/pep-0425/).
## [uv](./uv) ## [uv](./uv)
@ -70,8 +71,8 @@ Implements the traits defined in `uv-types`.
## [uv-distribution](./uv-distribution) ## [uv-distribution](./uv-distribution)
Client for interacting with built distributions (wheels) and source distributions (sdists). Client for interacting with built distributions (wheels) and source distributions (sdists). Capable
Capable of fetching metadata, distribution contents, etc. of fetching metadata, distribution contents, etc.
## [uv-extract](./uv-extract) ## [uv-extract](./uv-extract)

3
crates/install-wheel-rs/Readme.md
View file

@ -9,6 +9,7 @@ locked_venv = LockedVenv("path/to/.venv")
locked_venv.install_wheel("path/to/some_tagged_wheel.whl") locked_venv.install_wheel("path/to/some_tagged_wheel.whl")
``` ```
and there's only one function: `install_wheels_venv(wheels: List[str], venv: str)`, where `wheels` is a list of paths to wheel files and `venv` is the location of the venv to install the packages in. and there's only one function: `install_wheels_venv(wheels: List[str], venv: str)`, where `wheels`
is a list of paths to wheel files and `venv` is the location of the venv to install the packages in.
See monotrail for benchmarks. See monotrail for benchmarks.

37
crates/pep440-rs/CHANGELOG.md
View file

@ -1,51 +1,54 @@
## 0.3.12 ## 0.3.12
* Implement `FromPyObject` for `Version` - Implement `FromPyObject` for `Version`
## 0.3.11 ## 0.3.11
* CI fix - CI fix
## 0.3.10 ## 0.3.10
* Update pyo3 to 0.19 and maturin to 1.0 - Update pyo3 to 0.19 and maturin to 1.0
## 0.3.7 ## 0.3.7
* Add `major()`, `minor()` and `micro()` to `Version` by ischaojie ([#9](https://github.com/konstin/pep440-rs/pull/9)) - Add `major()`, `minor()` and `micro()` to `Version` by ischaojie
([#9](https://github.com/konstin/pep440-rs/pull/9))
* ## 0.3.6 - ## 0.3.6
* Fix Readme display - Fix Readme display
## 0.3.5 ## 0.3.5
* Make string serialization look more like poetry's - Make string serialization look more like poetry's
* Implement `__hash__` for `VersionSpecifier` - Implement `__hash__` for `VersionSpecifier`
## 0.3.4 ## 0.3.4
* Python bindings for `VersionSpecifiers` - Python bindings for `VersionSpecifiers`
## 0.3.3 ## 0.3.3
* Implement `Display` for `VersionSpecifiers` - Implement `Display` for `VersionSpecifiers`
## 0.3.2 ## 0.3.2
* Expose `VersionSpecifier().operator` and `VersionSpecifier().version` to Python - Expose `VersionSpecifier().operator` and `VersionSpecifier().version` to Python
## 0.3.1 ## 0.3.1
* Expose `Version` from `PyVersion` - Expose `Version` from `PyVersion`
## 0.3.0 ## 0.3.0
* Introduced a `PyVersion` wrapper specifically for the Python bindings to work around https://github.com/PyO3/pyo3/pull/2786 - Introduced a `PyVersion` wrapper specifically for the Python bindings to work around
* Added `VersionSpecifiers::contains` https://github.com/PyO3/pyo3/pull/2786
* Added `Version::from_release`, a constructor for a version that is just a release such as `3.8`. - Added `VersionSpecifiers::contains`
- Added `Version::from_release`, a constructor for a version that is just a release such as `3.8`.
## 0.2.0 ## 0.2.0
* Added `VersionSpecifiers`, a thin wrapper around `Vec<VersionSpecifier>` with a serde implementation. `VersionSpecifiers::from_str` is now preferred over `parse_version_specifiers`. - Added `VersionSpecifiers`, a thin wrapper around `Vec<VersionSpecifier>` with a serde
* Reexport rust function for python module implementation. `VersionSpecifiers::from_str` is now preferred over `parse_version_specifiers`.
- Reexport rust function for python module

34
crates/pep440-rs/Readme.md
View file

@ -4,9 +4,12 @@
[![PyPI](https://img.shields.io/pypi/v/pep440_rs.svg?logo=python&style=flat-square)](https://pypi.org/project/pep440_rs) [![PyPI](https://img.shields.io/pypi/v/pep440_rs.svg?logo=python&style=flat-square)](https://pypi.org/project/pep440_rs)
A library for python version numbers and specifiers, implementing A library for python version numbers and specifiers, implementing
[PEP 440](https://peps.python.org/pep-0440). See [Reimplementing PEP 440](https://cohost.org/konstin/post/514863-reimplementing-pep-4) for some background. [PEP 440](https://peps.python.org/pep-0440). See
[Reimplementing PEP 440](https://cohost.org/konstin/post/514863-reimplementing-pep-4) for some
background.
Higher level bindings to the requirements syntax are available in [pep508_rs](https://github.com/konstin/pep508_rs). Higher level bindings to the requirements syntax are available in
[pep508_rs](https://github.com/konstin/pep508_rs).
```rust ```rust
use std::str::FromStr; use std::str::FromStr;
@ -36,21 +39,22 @@ assert Version("2.0") in VersionSpecifier("==2")
PEP 440 has a lot of unintuitive features, including: PEP 440 has a lot of unintuitive features, including:
* An epoch that you can prefix the version which, e.g. `1!1.2.3`. Lower epoch always means lower - An epoch that you can prefix the version which, e.g. `1!1.2.3`. Lower epoch always means lower
version (`1.0 <=2!0.1`) version (`1.0 <=2!0.1`)
* post versions, which can be attached to both stable releases and pre-releases * post versions, which can be attached to both stable releases and pre-releases
* dev versions, which can be attached to sbpth table releases and pre-releases. When attached to a * dev versions, which can be attached to sbpth table releases and pre-releases. When attached to a
pre-release the dev version is ordered just below the normal pre-release, however when attached pre-release the dev version is ordered just below the normal pre-release, however when attached to
to a stable version, the dev version is sorted before a pre-releases a stable version, the dev version is sorted before a pre-releases
* pre-release handling is a mess: "Pre-releases of any kind, including developmental releases, * pre-release handling is a mess: "Pre-releases of any kind, including developmental releases, are
are implicitly excluded from all version specifiers, unless they are already present on the implicitly excluded from all version specifiers, unless they are already present on the system,
system, explicitly requested by the user, or if the only available version that satisfies explicitly requested by the user, or if the only available version that satisfies the version
the version specifier is a pre-release.". This means that we can't say whether a specifier specifier is a pre-release.". This means that we can't say whether a specifier matches without
matches without also looking at the environment also looking at the environment
* pre-release vs. pre-release incl. dev is fuzzy * pre-release vs. pre-release incl. dev is fuzzy
* local versions on top of all the others, which are added with a + and have implicitly typed * local versions on top of all the others, which are added with a + and have implicitly typed string
string and number segments and number segments
* no semver-caret (`^`), but a pseudo-semver tilde (`~=`) * no semver-caret (`^`), but a pseudo-semver tilde (`~=`)
* ordering contradicts matching: We have e.g. `1.0+local > 1.0` when sorting, * ordering contradicts matching: We have e.g. `1.0+local > 1.0` when sorting, but `==1.0` matches
but `==1.0` matches `1.0+local`. While the ordering of versions itself is a total order `1.0+local`. While the ordering of versions itself is a total order the version matching needs to
the version matching needs to catch all sorts of special cases catch all sorts of special cases

30
crates/pep440-rs/python/Readme.md
View file

@ -18,25 +18,27 @@ assert not VersionSpecifier(">=1.1").contains(Version("1.1a1"))
assert Version("2.0") in VersionSpecifier("==2") assert Version("2.0") in VersionSpecifier("==2")
``` ```
Unlike [pypa/packaging](https://github.com/pypa/packaging), this library always matches preleases. To only match final releases, filter with `.any_prelease()` beforehand. Unlike [pypa/packaging](https://github.com/pypa/packaging), this library always matches preleases.
To only match final releases, filter with `.any_prelease()` beforehand.
PEP 440 has a lot of unintuitive features, including: PEP 440 has a lot of unintuitive features, including:
* An epoch that you can prefix the version which, e.g. `1!1.2.3`. Lower epoch always means lower - An epoch that you can prefix the version which, e.g. `1!1.2.3`. Lower epoch always means lower
version (`1.0 <=2!0.1`) version (`1.0 <=2!0.1`)
* post versions, which can be attached to both stable releases and pre-releases * post versions, which can be attached to both stable releases and pre-releases
* dev versions, which can be attached to both table releases and pre-releases. When attached to a * dev versions, which can be attached to both table releases and pre-releases. When attached to a
pre-release the dev version is ordered just below the normal pre-release, however when attached pre-release the dev version is ordered just below the normal pre-release, however when attached to
to a stable version, the dev version is sorted before a pre-releases a stable version, the dev version is sorted before a pre-releases
* pre-release handling is a mess: "Pre-releases of any kind, including developmental releases, * pre-release handling is a mess: "Pre-releases of any kind, including developmental releases, are
are implicitly excluded from all version specifiers, unless they are already present on the implicitly excluded from all version specifiers, unless they are already present on the system,
system, explicitly requested by the user, or if the only available version that satisfies explicitly requested by the user, or if the only available version that satisfies the version
the version specifier is a pre-release.". This means that we can't say whether a specifier specifier is a pre-release.". This means that we can't say whether a specifier matches without
matches without also looking at the environment also looking at the environment
* pre-release vs. pre-release incl. dev is fuzzy * pre-release vs. pre-release incl. dev is fuzzy
* local versions on top of all the others, which are added with a + and have implicitly typed * local versions on top of all the others, which are added with a + and have implicitly typed string
string and number segments and number segments
* no semver-caret (`^`), but a pseudo-semver tilde (`~=`) * no semver-caret (`^`), but a pseudo-semver tilde (`~=`)
* ordering contradicts matching: We have e.g. `1.0+local > 1.0` when sorting, * ordering contradicts matching: We have e.g. `1.0+local > 1.0` when sorting, but `==1.0` matches
but `==1.0` matches `1.0+local`. While the ordering of versions itself is a total order `1.0+local`. While the ordering of versions itself is a total order the version matching needs to
the version matching needs to catch all sorts of special cases catch all sorts of special cases

22
crates/pep508-rs/Readme.md
View file

@ -3,7 +3,9 @@
[![Crates.io](https://img.shields.io/crates/v/pep508_rs.svg?logo=rust&style=flat-square)](https://crates.io/crates/pep508_rs) [![Crates.io](https://img.shields.io/crates/v/pep508_rs.svg?logo=rust&style=flat-square)](https://crates.io/crates/pep508_rs)
[![PyPI](https://img.shields.io/pypi/v/pep508_rs.svg?logo=python&style=flat-square)](https://pypi.org/project/pep508_rs) [![PyPI](https://img.shields.io/pypi/v/pep508_rs.svg?logo=python&style=flat-square)](https://pypi.org/project/pep508_rs)
A library for python [dependency specifiers](https://packaging.python.org/en/latest/specifications/dependency-specifiers/), better known as [PEP 508](https://peps.python.org/pep-0508/). A library for python
[dependency specifiers](https://packaging.python.org/en/latest/specifications/dependency-specifiers/),
better known as [PEP 508](https://peps.python.org/pep-0508/).
## Usage ## Usage
@ -32,13 +34,22 @@ assert requests.extras == ["security", "tests"]
assert [str(i) for i in requests.version_or_url] == [">= 2.8.1", "== 2.8.*"] assert [str(i) for i in requests.version_or_url] == [">= 2.8.1", "== 2.8.*"]
``` ```
Python bindings are built with [maturin](https://github.com/PyO3/maturin), but you can also use the normal `pip install .` Python bindings are built with [maturin](https://github.com/PyO3/maturin), but you can also use the
normal `pip install .`
`Version` and `VersionSpecifier` from [pep440_rs](https://github.com/konstin/pep440-rs) are reexported to avoid type mismatches. `Version` and `VersionSpecifier` from [pep440_rs](https://github.com/konstin/pep440-rs) are
reexported to avoid type mismatches.
## Markers ## Markers
Markers allow you to install dependencies only in specific environments (python version, operating system, architecture, etc.) or when a specific feature is activated. E.g. you can say `importlib-metadata ; python_version < "3.8"` or `itsdangerous (>=1.1.0) ; extra == 'security'`. Unfortunately, the marker grammar has some oversights (e.g. <https://github.com/pypa/packaging.python.org/pull/1181>) and the design of comparisons (PEP 440 comparisons with lexicographic fallback) leads to confusing outcomes. This implementation tries to carefully validate everything and emit warnings whenever bogus comparisons with unintended semantics are made. Markers allow you to install dependencies only in specific environments (python version, operating
system, architecture, etc.) or when a specific feature is activated. E.g. you can say
`importlib-metadata ; python_version < "3.8"` or `itsdangerous (>=1.1.0) ; extra == 'security'`.
Unfortunately, the marker grammar has some oversights (e.g.
<https://github.com/pypa/packaging.python.org/pull/1181>) and the design of comparisons (PEP 440
comparisons with lexicographic fallback) leads to confusing outcomes. This implementation tries to
carefully validate everything and emit warnings whenever bogus comparisons with unintended semantics
are made.
In python, warnings are by default sent to the normal python logging infrastructure: In python, warnings are by default sent to the normal python logging infrastructure:
@ -56,13 +67,12 @@ assert Requirement(
).evaluate_markers(env, ["science"]) ).evaluate_markers(env, ["science"])
``` ```
```python ```python
from pep508_rs import Requirement, MarkerEnvironment from pep508_rs import Requirement, MarkerEnvironment
env = MarkerEnvironment.current() env = MarkerEnvironment.current()
Requirement("numpy; python_version >= '3.9.'").evaluate_markers(env, []) Requirement("numpy; python_version >= '3.9.'").evaluate_markers(env, [])
# This will log: # This will log:
# "Expected PEP 440 version to compare with python_version, found '3.9.', " # "Expected PEP 440 version to compare with python_version, found '3.9.', "
# "evaluating to false: Version `3.9.` doesn't match PEP 440 rules" # "evaluating to false: Version `3.9.` doesn't match PEP 440 rules"
``` ```

117
crates/uv-trampoline/README.md
View file

@ -1,13 +1,14 @@
# Windows trampolines # Windows trampolines
This is a fork of [posy trampolines](https://github.com/njsmith/posy/tree/dda22e6f90f5fefa339b869dd2bbe107f5b48448/src/trampolines/windows-trampolines/posy-trampoline). This is a fork of
[posy trampolines](https://github.com/njsmith/posy/tree/dda22e6f90f5fefa339b869dd2bbe107f5b48448/src/trampolines/windows-trampolines/posy-trampoline).
## Building ## Building
### Cross-compiling from Linux ### Cross-compiling from Linux
Install [cargo xwin](https://github.com/rust-cross/cargo-xwin). Use your Install [cargo xwin](https://github.com/rust-cross/cargo-xwin). Use your package manager to install
package manager to install LLD and add the `rustup` targets: LLD and add the `rustup` targets:
```shell ```shell
sudo apt install llvm clang lld sudo apt install llvm clang lld
@ -26,8 +27,8 @@ cargo +nightly-2024-06-08 xwin build --release --target aarch64-pc-windows-msvc
### Cross-compiling from macOS ### Cross-compiling from macOS
Install [cargo xwin](https://github.com/rust-cross/cargo-xwin). Use your Install [cargo xwin](https://github.com/rust-cross/cargo-xwin). Use your package manager to install
package manager to install LLVM and add the `rustup` targets: LLVM and add the `rustup` targets:
```shell ```shell
brew install llvm brew install llvm
@ -59,8 +60,8 @@ cp target/i686-pc-windows-msvc/release/uv-trampoline-gui.exe trampolines/uv-tram
### Testing the trampolines ### Testing the trampolines
To perform a basic smoke test of the trampolines, run the following commands on a Windows machine, from the root of the To perform a basic smoke test of the trampolines, run the following commands on a Windows machine,
repository: from the root of the repository:
```shell ```shell
cargo clean cargo clean
@ -73,98 +74,86 @@ cargo run pip install black
### What is this? ### What is this?
Sometimes you want to run a tool on Windows that's written in Python, like Sometimes you want to run a tool on Windows that's written in Python, like `black` or `mypy` or
`black` or `mypy` or `jupyter` or whatever. But, Windows does not know how to `jupyter` or whatever. But, Windows does not know how to run Python files! It knows how to run
run Python files! It knows how to run `.exe` files. So we need to somehow `.exe` files. So we need to somehow convert our Python file a `.exe` file.
convert our Python file a `.exe` file.
That's what this does: it's a generic "trampoline" that lets us generate custom That's what this does: it's a generic "trampoline" that lets us generate custom `.exe`s for
`.exe`s for arbitrary Python scripts, and when invoked it bounces to invoking arbitrary Python scripts, and when invoked it bounces to invoking `python <the script>` instead.
`python <the script>` instead.
### How do you use it? ### How do you use it?
Basically, this looks up `python.exe` (for console programs) Basically, this looks up `python.exe` (for console programs) and invokes
and invokes `python.exe path\to\the\<the .exe>`. `python.exe path\to\the\<the .exe>`.
The intended use is: The intended use is:
* take your Python script, name it `__main__.py`, and pack it - take your Python script, name it `__main__.py`, and pack it into a `.zip` file. Then concatenate
into a `.zip` file. Then concatenate that `.zip` file onto the end of one of our that `.zip` file onto the end of one of our prebuilt `.exe`s.
prebuilt `.exe`s. - After the zip file content, write the path to the Python executable that the script uses to run
* After the zip file content, write the path to the Python executable that the script uses to run
the Python script as UTF-8 encoded string, followed by the path's length as a 32-bit little-endian the Python script as UTF-8 encoded string, followed by the path's length as a 32-bit little-endian
integer. integer.
* At the very end, write the magic number `UVUV` in bytes. - At the very end, write the magic number `UVUV` in bytes.
| `launcher.exe` | | `launcher.exe` |
|:---------------------------:| | :-------------------------: |
| `<zipped python script>` | | `<zipped python script>` |
| `<path to python.exe>` | | `<path to python.exe>` |
| `<len(path to python.exe)>` | | `<len(path to python.exe)>` |
| `<b'U', b'V', b'U', b'V'>` | | `<b'U', b'V', b'U', b'V'>` |
Then when you run `python` on the `.exe`, it will see the `.zip` trailer at the Then when you run `python` on the `.exe`, it will see the `.zip` trailer at the end of the `.exe`,
end of the `.exe`, and automagically look inside to find and execute and automagically look inside to find and execute `__main__.py`. Easy-peasy.
`__main__.py`. Easy-peasy.
### Why does this exist? ### Why does this exist?
I probably could have used Vinay's C++ implementation from `distlib`, but what's I probably could have used Vinay's C++ implementation from `distlib`, but what's the fun in that? In
the fun in that? In particular, optimizing for binary size was entertaining particular, optimizing for binary size was entertaining (these are ~7x smaller than the distlib,
(these are ~7x smaller than the distlib, which doesn't matter much, but does a which doesn't matter much, but does a little bit, considering that it gets added to every Python
little bit, considering that it gets added to every Python script). There are script). There are also some minor advantages, like I think the Rust code is easier to understand
also some minor advantages, like I think the Rust code is easier to understand (multiple files!) and it's convenient to be able to straightforwardly code the Python-finding logic
(multiple files!) and it's convenient to be able to straightforwardly code the we want. But mostly it was just an interesting challenge.
Python-finding logic we want. But mostly it was just an interesting challenge.
This does owe a *lot* to the `distlib` implementation though. The overall logic This does owe a _lot_ to the `distlib` implementation though. The overall logic is copied
is copied more-or-less directly. more-or-less directly.
### Anything I should know for hacking on this? ### Anything I should know for hacking on this?
In order to minimize binary size, this uses, `panic="abort"`, and carefully In order to minimize binary size, this uses, `panic="abort"`, and carefully avoids using
avoids using `core::fmt`. This removes a bunch of runtime overhead: by `core::fmt`. This removes a bunch of runtime overhead: by default, Rust "hello world" on Windows is
default, Rust "hello world" on Windows is ~150 KB! So these binaries are ~10x ~150 KB! So these binaries are ~10x smaller.
smaller.
Of course the tradeoff is that this is an awkward super-limited Of course the tradeoff is that this is an awkward super-limited environment. No C runtime and
environment. No C runtime and limited platform APIs... you don't limited platform APIs... you don't even panicking support by default. To work around this:
even panicking support by default. To work around this:
- We use `windows` to access Win32 APIs directly. Who needs a C runtime? - We use `windows` to access Win32 APIs directly. Who needs a C runtime? Though uh, this does mean
Though uh, this does mean that literally all of our code is `unsafe`. Sorry! that literally all of our code is `unsafe`. Sorry!
- `diagnostics.rs` uses `ufmt` and some cute Windows tricks to get a convenient - `diagnostics.rs` uses `ufmt` and some cute Windows tricks to get a convenient version of
version of `eprintln!` that works without `core::fmt`, and automatically prints `eprintln!` that works without `core::fmt`, and automatically prints to either the console if
to either the console if available or pops up a message box if not. available or pops up a message box if not.
- All the meat is in `bounce.rs`. - All the meat is in `bounce.rs`.
Miscellaneous tips: Miscellaneous tips:
- `cargo-bloat` is a useful tool for checking what code is ending up in the - `cargo-bloat` is a useful tool for checking what code is ending up in the final binary and how
final binary and how much space it's taking. (It makes it very obvious whether much space it's taking. (It makes it very obvious whether you've pulled in `core::fmt`!)
you've pulled in `core::fmt`!)
- Lots of Rust built-in panicking checks will pull in `core::fmt`, e.g., if you - Lots of Rust built-in panicking checks will pull in `core::fmt`, e.g., if you ever use `.unwrap()`
ever use `.unwrap()` then suddenly our binaries double in size, because the then suddenly our binaries double in size, because the `if foo.is_none() { panic!(...) }` that's
`if foo.is_none() { panic!(...) }` that's hidden inside `.unwrap()` will hidden inside `.unwrap()` will invoke `core::fmt`, even if the unwrap will actually never fail.
invoke `core::fmt`, even if the unwrap will actually never fail. `.unwrap_unchecked()` avoids this. Similar for `slice[idx]` vs `slice.get_unchecked(idx)`.
`.unwrap_unchecked()` avoids this. Similar for `slice[idx]` vs
`slice.get_unchecked(idx)`.
### How do you build this stupid thing? ### How do you build this stupid thing?
Building this can be frustrating, because the low-level compiler/runtime Building this can be frustrating, because the low-level compiler/runtime machinery have a bunch of
machinery have a bunch of implicit assumptions about the environment they'll run implicit assumptions about the environment they'll run in, and the facilities it provides for things
in, and the facilities it provides for things like `memcpy`, unwinding, etc. like `memcpy`, unwinding, etc. So we need to replace the bits that we actually need, and which bits
So we need to replace the bits that we actually need, and which bits we need we need can change depending on stuff like optimization options. For example: we use
can change depending on stuff like optimization options. `panic="abort"`, so we don't actually need unwinding support, but at lower optimization levels the
For example: we use `panic="abort"`, so we don't actually need unwinding support, compiler might not realize that, and still emit references to the unwinding
but at lower optimization levels the compiler might not realize that, and still helper`__CxxFrameHandler3`. And then the linker blows up because that symbol doesn't exist.
emit references to the unwinding helper`__CxxFrameHandler3`. And then the linker
blows up because that symbol doesn't exist.
``` ```
cargo build --release --target i686-pc-windows-msvc cargo build --release --target i686-pc-windows-msvc

16
docs/concepts/cache.md
View file

@ -10,9 +10,9 @@ The specifics of uv's caching semantics vary based on the nature of the dependen
- **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 the - **For direct URL dependencies**, uv respects HTTP caching headers, and also caches based on the
URL itself. URL itself.
- **For Git dependencies**, uv caches based on the fully-resolved Git commit hash. As such, `uv pip - **For Git dependencies**, uv caches based on the fully-resolved Git commit hash. As such,
compile` will pin Git dependencies to a specific commit hash when writing the resolved dependency `uv pip compile` will pin Git dependencies to a specific commit hash when writing the resolved
set. dependency 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.
@ -28,8 +28,8 @@ are running, and _never_ safe to modify the cache directly (e.g., by removing a
If you're running into caching issues, uv includes a few escape hatches: 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 - To force uv to revalidate cached data for a specific dependency, run, e.g.,
--refresh-package flask ...`. `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
@ -38,10 +38,10 @@ 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 - `uv cache clean ruff` removes all cache entries for the `ruff` package, useful for invalidating
the cache for a single or finite set of packages. 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 - `uv cache prune` removes all _unused_ cache entries. For example, the cache directory may contain
entries created in previous uv versions that are no longer necessary and can be safely removed. entries created in previous uv versions that are no longer necessary and can be safely removed.
`uv cache prune` is safe to run periodically, to keep the cache directory clean. `uv cache prune` is safe to run periodically, to keep the cache directory clean.
## Caching in continuous integration ## Caching in continuous integration

41
docs/concepts/dependencies.md
View file

@ -89,9 +89,9 @@ $ 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 = Git dependencies can also be manually added or edited in the `pyproject.toml` with the
<url> }` syntax. A target revision may be specified with one of: `rev`, `tag`, or `branch`. A `{ git = <url> }` syntax. A target revision may be specified with one of: `rev`, `tag`, or `branch`.
`subdirectory` may be specified if the package isn't in the repository root. A `subdirectory` may be specified if the package isn't in the repository root.
### URL ### URL
@ -116,9 +116,9 @@ 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 dependencies can also be manually added or edited in the `pyproject.toml` with the
<url> }` syntax. A `subdirectory` may be specified if the if the source distribution isn't in the `{ url = <url> }` syntax. A `subdirectory` may be specified if the if the source distribution isn't
archive root. in the archive root.
### Path ### Path
@ -157,15 +157,15 @@ $ uv add ~/projects/bar/
!!! important !!! important
An [editable installation](#editables-dependencies) is not used for path dependencies by An [editable installation](#editables-dependencies) is not used for path dependencies by
default. An editable installation may be requested for project directories: default. An editable installation may be requested for project directories:
```console ```console
$ uv add --editable ~/projects/bar/ $ uv add --editable ~/projects/bar/
``` ```
However, it is recommended to use [_workspaces_](#workspaces) instead of manual path However, it is recommended to use [_workspaces_](#workspaces) instead of manual path
dependencies. dependencies.
### Workspace member ### Workspace member
@ -193,9 +193,9 @@ include = [
## Optional dependencies ## Optional dependencies
It is common for projects that are published as libraries to make some features optional to reduce It is common for projects that are published as libraries to make some features optional to reduce
the default dependency tree. For example, Pandas has an [`excel` the default dependency tree. For example, Pandas has an
extra](https://pandas.pydata.org/docs/getting_started/install.html#excel-files) and a [`plot` [`excel` extra](https://pandas.pydata.org/docs/getting_started/install.html#excel-files) and a
extra](https://pandas.pydata.org/docs/getting_started/install.html#visualization) to avoid [`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 installation of Excel parsers and `matplotlib` unless someone explicitly requires them. Extras are
requested with the `package[<extra>]` syntax, e.g., `pandas[plot, excel]`. requested with the `package[<extra>]` syntax, e.g., `pandas[plot, excel]`.
@ -233,7 +233,7 @@ $ uv add httpx --optional network
Unlike optional dependencies, development dependencies are local-only and will _not_ be included in 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 the project requirements when published to PyPI or other indexes. As such, development dependencies
are included under `[tool.uv]` instead of `[project]`. 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.
@ -269,18 +269,19 @@ 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] Extras are comma-separated in square bracket between name and version, e.g.,
==2.2`. Whitespace between extra names is ignored. `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'`. To `importlib.metadata` module, use `importlib-metadata >=7.1.0,<8; python_version < '3.10'`. To
install `colorama` on Windows (but omit it on other platforms), use `colorama >=0.4.6,<5; install `colorama` on Windows (but omit it on other platforms), use
platform_system == "Windows"`. `colorama >=0.4.6,<5; platform_system == "Windows"`.
Markers are combined with `and`, `or`, and parentheses, e.g., `aiohttp >=3.7.4,<4; (sys_platform != Markers are combined with `and`, `or`, and parentheses, e.g.,
'win32' or implementation_name != 'pypy') and python_version >= '3.10'`. Note that versions within `aiohttp >=3.7.4,<4; (sys_platform != 'win32' or implementation_name != 'pypy') and python_version >= '3.10'`.
markers must be quoted, while versions _outside_ of markers must _not_ be quoted. Note that versions within markers must be quoted, while versions _outside_ of markers must _not_ be
quoted.
## Editable dependencies ## Editable dependencies

33
docs/concepts/projects.md
View file

@ -8,7 +8,7 @@ Python projects help manage Python applications spanning multiple files.
## Project metadata ## Project metadata
Python project metadata is defined in a `pyproject.toml` file. Python project metadata is defined in a `pyproject.toml` file.
`uv init` can be used to create a new project, with a basic `pyproject.toml` and package definition. `uv init` can be used to create a new project, with a basic `pyproject.toml` and package definition.
@ -32,8 +32,8 @@ This Python version requirement determines what syntax is valid in the project a
versions of dependencies which can be used (they must support the same Python range). 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 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 dependency list from the command line with `uv add` and `uv remove`. uv also supports
package sources](./dependencies.md) for advanced users. [extended package sources](./dependencies.md) for advanced users.
!!! tip !!! tip
@ -51,13 +51,13 @@ To run a command in the project environment, use `uv run`. Alternatively the pro
be activated as normal for a virtual environment. 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 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 it is up to date if it exists. The project environment can also be explicitly created with
sync`. `uv sync`.
It is _not_ recommended to modify the project environment manually, e.g., with `uv pip install`. For 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, project dependencies, use `uv add` to add a package to the environment. For one-off requirements,
use [`uvx`](../guides/tools.md) or [`uv run use [`uvx`](../guides/tools.md) or
--with`](#running-commands-with-additional-dependencies). [`uv run --with`](#running-commands-with-additional-dependencies).
## Lockfile ## Lockfile
@ -80,7 +80,7 @@ The lockfile is created and updated during uv invocations that use the project e
`uv.lock` is a human-readable TOML file but is managed by uv and should not be edited manually. `uv.lock` is a human-readable TOML file but is managed by uv and should not be edited manually.
There is no Python standard for lockfiles at this time, so the format of this file is specific to uv 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. 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.
@ -97,11 +97,11 @@ To add a dependency:
$ uv add httpx $ uv add httpx
``` ```
uv supports adding [editable dependencies](./dependencies.md#editable-dependencies), [development uv supports adding [editable dependencies](./dependencies.md#editable-dependencies),
dependencies](./dependencies.md#development-dependencies), [optional [development dependencies](./dependencies.md#development-dependencies),
dependencies](./dependencies.md#optional-dependencies), and alternative [dependency [optional dependencies](./dependencies.md#optional-dependencies), and alternative
sources](./dependencies.md#dependency-sources). See the [dependency [dependency sources](./dependencies.md#dependency-sources). See the
specification](./dependencies.md) documentation for more details. [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.:
@ -138,8 +138,9 @@ $ 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 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 isolated from the current shell by default, so invocations that require the project, e.g.,
-c "import example"`, will fail. Instead, use `uv run` to run commands in the project environment: `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"
@ -173,7 +174,7 @@ $ uv run --with httpx==0.25.0 python -c "import httpx; print(httpx.__version__)"
``` ```
The requested version will be respected regardless of the project's requirements. For example, even 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. if the project requires `httpx==0.24.0`, the output above would be the same.
### Running scripts ### Running scripts

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

@ -1,20 +1,20 @@
# Python versions # Python versions
A Python version is composed of a Python interpreter (i.e. the `python` executable), the standard A Python version is composed of a Python interpreter (i.e. the `python` executable), the standard
library, and other supporting files. library, and other supporting files.
## Managed and system Python installations ## Managed and system Python installations
Since it is common for a system to have an existing Python installation, uv supports Since it is common for a system to have an existing Python installation, uv supports
[discovering](#discovery-of-python-versions) Python versions. However, uv also supports [installing [discovering](#discovery-of-python-versions) Python versions. However, uv also supports
Python versions](#installing-a-python-version) itself. To distinguish between these two types of [installing Python versions](#installing-a-python-version) itself. To distinguish between these two
Python installations, uv refers to Python versions it installs as _managed_ Python installations and types of Python installations, uv refers to Python versions it installs as _managed_ Python
all other Python installations as _system_ Python installations. installations and all other Python installations as _system_ Python installations.
!!! note !!! note
uv does not distinguish between Python versions installed by the operating system vs those uv does not distinguish between Python versions installed by the operating system vs those
installed and managed by other tools. For example, if a Python installation is managed with installed and managed by other tools. For example, if a Python installation is managed with
`pyenv`, it would still be considered a _system_ Python version in uv. `pyenv`, it would still be considered a _system_ Python version in uv.
## Requesting a version ## Requesting a version
@ -46,8 +46,8 @@ Additionally, a specific system Python interpreter can be requested with:
- `<install-dir>` e.g. `/some/environment/` - `<install-dir>` e.g. `/some/environment/`
By default, uv will automatically download Python versions if they cannot be found on the system. By default, uv will automatically download Python versions if they cannot be found on the system.
This behavior can be [disabled with the `python-fetch` This behavior can be
option](#disabling-automatic-python-downloads). [disabled with the `python-fetch` option](#disabling-automatic-python-downloads).
## Installing a Python version ## Installing a Python version
@ -130,8 +130,8 @@ uv python list --only-installed
When searching for a Python version, the following locations are checked: When searching for a Python version, the following locations are checked:
- Managed Python installations in the `UV_PYTHON_INSTALL_DIR`. - Managed Python installations in the `UV_PYTHON_INSTALL_DIR`.
- A Python interpreter on the `PATH` as `python`, `python3`, or `python3.x` on macOS and Linux, or `python.exe` - A Python interpreter on the `PATH` as `python`, `python3`, or `python3.x` on macOS and Linux, or
on Windows. `python.exe` on Windows.
- 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.
@ -152,7 +152,7 @@ The `python-fetch` option can be used to disable this behavior. By default, it i
## 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 By default, uv will attempt to use Python versions found on the system and only download managed
interpreters when necessary. interpreters when necessary.
The `python-preference` option can be used to adjust this behavior. By default, it is set to The `python-preference` option can be used to adjust this behavior. By default, it is set to
`managed` which prefers managed Python installations over system Python installations. However, `managed` which prefers managed Python installations over system Python installations. However,
@ -161,8 +161,8 @@ system Python installations are still preferred over downloading a managed Pytho
The following alternative options are available: The following alternative options are available:
- `only-managed`: Only use managed Python installations; never use system Python installations - `only-managed`: Only use managed Python installations; never use system Python installations
- `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 These options allow disabling uv's managed Python versions entirely or always using them and
ignoring any existing system installations. ignoring any existing system installations.
@ -199,14 +199,13 @@ distributions from the
[`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. 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. project is partially maintained by the uv maintainers and is used by many other Python projects.
The uv Python distributions are self-contained, highly-portable, and performant. While The uv Python distributions are self-contained, highly-portable, and performant. While Python can be
Python can be built from source, as in tools like `pyenv`, it requires preinstalled system built from source, as in tools like `pyenv`, it requires preinstalled system dependencies and
dependencies and creating optimized, performant builds is very slow. creating optimized, performant builds is very slow.
These distributions have some behavior quirks, generally as a consequence of portability. See the These distributions have some behavior quirks, generally as a consequence of portability. See the
[`python-build-standalone` [`python-build-standalone` quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html)
quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) documentation for documentation for details.
details.
### PyPy distributions ### PyPy distributions

29
docs/concepts/resolution.md
View file

@ -75,10 +75,11 @@ Alternatively, you can add the transitive dependency to your `requirements.in` f
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 Pre-releases are
difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to model, and are a [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to
frequent source of bugs in other packaging tools. uv's pre-release handling is _intentionally_ model, and are a frequent source of bugs in other packaging tools. uv's pre-release handling is
limited and _intentionally_ requires user opt-in for pre-releases, to ensure correctness. _intentionally_ limited and _intentionally_ requires user opt-in for pre-releases, to ensure
correctness.
For more, see ["Pre-release compatibility"](../pip/compatibility.md#pre-release-compatibility) For more, see ["Pre-release compatibility"](../pip/compatibility.md#pre-release-compatibility)
@ -88,8 +89,8 @@ Historically, `pip` has supported "constraints" (`-c constraints.txt`), which al
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 acceptable versions of a package across the dependency tree via overrides
overrides.txt`). (`--override overrides.txt`).
In short, overrides allow the user to lie to the resolver by overriding the declared dependencies of In short, overrides allow the user to lie to the resolver by overriding the declared dependencies of
a package. Overrides are a useful last resort for cases in which the user knows that a dependency is a package. Overrides are a useful last resort for cases in which the user knows that a dependency is
@ -125,11 +126,12 @@ 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 `uv pip For example, if you're running uv on macOS, but want to resolve for Linux, you can run
compile --python-platform linux requirements.in` to produce a `manylinux2014`-compatible resolution. `uv pip compile --python-platform linux requirements.in` to produce a `manylinux2014`-compatible
resolution.
Similarly, if you're running uv on Python 3.9, but want to resolve for Python 3.8, you can run `uv Similarly, if you're running uv on Python 3.9, but want to resolve for Python 3.8, you can run
pip compile --python-version 3.8 requirements.in` to produce a Python 3.8-compatible resolution. `uv pip compile --python-version 3.8 requirements.in` to produce a Python 3.8-compatible resolution.
The `--python-platform` and `--python-version` arguments can be combined to produce a resolution for The `--python-platform` and `--python-version` arguments can be combined to produce a resolution for
a specific platform and Python version, enabling users to generate multiple lockfiles for different a specific platform and Python version, enabling users to generate multiple lockfiles for different
@ -144,7 +146,6 @@ environments from a single machine.
compatible with any machine running on the target `--python-platform`, which should be sufficient for compatible with any machine running on the target `--python-platform`, which should be sufficient for
most use cases, but may lose fidelity for complex package and platform combinations. most use cases, but may lose fidelity for complex package and platform combinations.
## Time-restricted reproducible resolutions ## Time-restricted reproducible resolutions
uv supports an `--exclude-newer` option to limit resolution to distributions published before a uv supports an `--exclude-newer` option to limit resolution to distributions published before a
@ -152,9 +153,9 @@ specific date, allowing reproduction of installations regardless of new package
may be specified as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamp (e.g., may be specified as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamp (e.g.,
`2006-12-02T02:07:43Z`) or UTC date in the same format (e.g., `2006-12-02`). `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 Note the package index must support the `upload-time` field as specified in
700`](https://peps.python.org/pep-0700/). If the field is not present for a given distribution, the [`PEP 700`](https://peps.python.org/pep-0700/). If the field is not present for a given
distribution will be treated as unavailable. distribution, the distribution will be treated as unavailable.
To ensure reproducibility, messages for unsatisfiable resolutions will not mention that To ensure reproducibility, messages for unsatisfiable resolutions will not mention that
distributions were excluded due to the `--exclude-newer` flag — newer distributions will be treated distributions were excluded due to the `--exclude-newer` flag — newer distributions will be treated

8
docs/concepts/tools.md
View file

@ -2,13 +2,13 @@
Tools are Python packages that provide command-line interfaces. Tools can be invoked without 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 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 environment isolated from the current project. Alternatively, tools can be installed with
install`, in which case their executables are placed in the `PATH` — an isolated virtual environment `uv tool install`, in which case their executables are placed in the `PATH` — an isolated virtual
is still used but it is not treated as disposable. 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 See the [tools guide](../guides/tools.md) for an introduction to working with the tools
interface — this document discusses details of tool management. interface — this document discusses details of tool management.
## Tool environments ## Tool environments

8
docs/concepts/workspaces.md
View file

@ -4,9 +4,9 @@ Workspaces help organize large codebases by splitting them into multiple package
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. `uv dependencies. Using the uv project interface, all of the workspace packages are locked together.
run` installs only the current package (unless overridden with `--package`) and its workspace and `uv run` installs only the current package (unless overridden with `--package`) and its workspace
non-workspace dependencies. and non-workspace dependencies.
## Configuration ## Configuration
@ -25,7 +25,7 @@ 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 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 packages in `packages`. In this example `albatross/pyproject.toml` has both a `project` section and

8
docs/configuration/authentication.md
View file

@ -10,8 +10,8 @@ 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 See the
documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) [GitHub SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh)
for more details on how to configure SSH. for more details on how to configure SSH.
Using a password or token: Using a password or token:
@ -25,8 +25,8 @@ When using a GitHub personal access token, the username is arbitrary. GitHub doe
logging in with password directly, although other hosts may. If a username is provided without logging in with password directly, although other hosts may. If a username is provided without
credentials, you will be prompted to enter them. credentials, you will be prompted to enter them.
If there are no credentials present in the URL and authentication is needed, the [Git credential If there are no credentials present in the URL and authentication is needed, the
helper](https://git-scm.com/doc/credential-helpers) will be queried. [Git credential helper](https://git-scm.com/doc/credential-helpers) will be queried.
## HTTP authentication ## HTTP authentication

4
docs/configuration/environment.md
View file

@ -64,8 +64,8 @@ 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 enable trace-level logging. See the
documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax) [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

4
docs/configuration/index.md
View file

@ -6,5 +6,5 @@ Read about the various ways to configure uv:
- [Using environment variables](./environment.md) - [Using environment variables](./environment.md)
- [Configuring authentication](./authentication.md) - [Configuring authentication](./authentication.md)
Or, jump to the [settings reference](../reference/settings.md) which enumerates the available configuration Or, jump to the [settings reference](../reference/settings.md) which enumerates the available
options. configuration options.

1
docs/features.md
View file

@ -1,4 +1,3 @@
# Features # Features
uv supports the full Python development experience — from installing Python and hacking on simple uv supports the full Python development experience — from installing Python and hacking on simple

10
docs/first-steps.md
View file

@ -11,8 +11,8 @@ $ uv
You should see a help menu listing the available commands. You should see a help menu listing the available commands.
Read on for a brief overview of the help menu and version command, or jump to an [overview of Read on for a brief overview of the help menu and version command, or jump to an
features](./features.md) to start using uv. [overview of features](./features.md) to start using uv.
## Help menus ## Help menus
@ -44,7 +44,6 @@ $ uv help init
When using the long help menu, uv will attempt to use `less` or `more` to "page" the output so it is 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`. not all displayed at once. To exit the pager, press `q`.
## Viewing the version ## Viewing the version
To check the installed version: To check the installed version:
@ -63,5 +62,6 @@ $ uv pip --version # Can be used with a subcommand
## Next steps ## Next steps
Now that you've confirmed uv is installed and know how to get help, check out an [overview of Now that you've confirmed uv is installed and know how to get help, check out an
features](./features.md) or jump straight into the [guides](./guides/index.md) to start using uv. [overview of features](./features.md) or jump straight into the [guides](./guides/index.md) to start
using uv.

8
docs/guides/index.md
View file

@ -1,11 +1,11 @@
# Guides overview # Guides overview
Check out one of the core guides to get started: Check out one of the core guides to get started:
- [Installing Python versions](./install-python.md) - [Installing Python versions](./install-python.md)
- [Running scripts and declaring dependencies](./scripts.md) - [Running scripts and declaring dependencies](./scripts.md)
- [Running and installing applications as tools](./tools.md) - [Running and installing applications as tools](./tools.md)
- [Creating and working on projects](./projects.md) - [Creating and working on projects](./projects.md)
Learn how to integrate uv with other software: Learn how to integrate uv with other software:

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

@ -1,8 +1,8 @@
# Installing Python # Installing Python
If Python is already installed on your system, uv will [detect and If Python is already installed on your system, uv will
use](#using-an-existing-python-installation) it without configuration. However, uv can also install [detect and use](#using-an-existing-python-installation) it without configuration. However, uv can
and manage Python versions for you. also install and manage Python versions for you.
!!! tip !!! tip
@ -21,7 +21,6 @@ system.
Python does not publish official distributable binaries so uv uses third-party 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. See the [Python distributions](../concepts/python-versions.md#python-distributions) documentation for more details. Python does not publish official distributable binaries so uv uses third-party 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. See the [Python distributions](../concepts/python-versions.md#python-distributions) documentation for more details.
<!-- TODO(zanieb): Restore when Python shim management is added <!-- TODO(zanieb): Restore when Python shim management is added
Note that when an automatic Python installation occurs, the `python` command will not be added to the shell. Use `uv python install-shim` to ensure the `python` shim is installed. Note that when an automatic Python installation occurs, the `python` command will not be added to the shell. Use `uv python install-shim` to ensure the `python` shim is installed.
@ -86,8 +85,8 @@ Note that when an automatic Python installation occurs, the `python` command wil
uv will also use an existing Python installation if already present on your system. There is no 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 configuration necessary for this behavior: uv will use the system Python if it satisfies the
requirements of the command invocation. See the [Python requirements of the command invocation. See the
discovery](../concepts/python-versions.md#discovery-order) documentation for details. [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 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) [Python version preference](../concepts/python-versions.md#adjusting-python-version-preferences)

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

@ -6,16 +6,16 @@ some initial setup.
## Azure Artifacts ## Azure Artifacts
uv can install packages from [Azure DevOps uv can install packages from
Artifacts](https://learn.microsoft.com/en-us/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget%2Cnugetserver). [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 Authenticate to a feed using a
Token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows) [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. (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 If there is a PAT available (eg
pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken)), [`$(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 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. password field of the URL. A username must be included as well, but can be any string.
@ -27,21 +27,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 If there is not a PAT available, authenticate to Artifacts using the
[`keyring`](https://github.com/jaraco/keyring) package with [the `artifacts-keyring` [`keyring`](https://github.com/jaraco/keyring) package with
plugin](https://github.com/Microsoft/artifacts-keyring). Because these two packages are required to [the `artifacts-keyring` plugin](https://github.com/Microsoft/artifacts-keyring). Because these two
authenticate to Azure Artifacts, they must be pre-installed from a source other than Artifacts. 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 The `artifacts-keyring` plugin wraps
tool](https://github.com/microsoft/artifacts-credprovider). The credential provider supports a few [the Azure Artifacts Credential Provider tool](https://github.com/microsoft/artifacts-credprovider).
different authentication modes including interactive login — see [the tool's The credential provider supports a few different authentication modes including interactive login —
documentation](https://github.com/microsoft/artifacts-credprovider) for information on see [the tool's documentation](https://github.com/microsoft/artifacts-credprovider) for information
configuration. on configuration.
uv only supports using the `keyring` package in [subprocess uv only supports using the `keyring` package in
mode](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#registry-authentication). The [subprocess mode](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#registry-authentication).
`keyring` executable must be in the `PATH`, i.e., installed globally or in the active environment. The `keyring` executable must be in the `PATH`, i.e., installed globally or in the active
The `keyring` CLI requires a username in the URL, so the index URL must include the default username environment. The `keyring` CLI requires a username in the URL, so the index URL must include the
`VssSessionToken`. 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

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

@ -162,7 +162,6 @@ jobs:
uv-${{ runner.os }}-${{ hashFiles('uv.lock') }} uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
uv-${{ runner.os }} uv-${{ runner.os }}
# ... install packages, run tests, etc ... # ... install packages, run tests, etc ...
- name: Minimize uv cache - name: Minimize uv cache

11
docs/guides/projects.md
View file

@ -66,12 +66,12 @@ dev-dependencies = []
``` ```
This is where you specify dependencies, as well as details about the project such as it's This is where you specify dependencies, as well as details about the project such as it's
description or license. You can edit this file manually, or use commands like `uv add` and `uv description or license. You can edit this file manually, or use commands like `uv add` and
remove` to manage your project through the CLI. `uv remove` to manage your project through the CLI.
!!! tip !!! tip
See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-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 the `pyproject.toml` format. for more details on getting started with the `pyproject.toml` format.
### `.venv` ### `.venv`
@ -122,7 +122,6 @@ $ uv remove requests
See the documentation on [managing dependencies](../concepts/projects.md#managing-dependencies) for See the documentation on [managing dependencies](../concepts/projects.md#managing-dependencies) for
more details. more details.
## Running commands ## Running commands
`uv run` can be used to run arbitrary scripts or commands in your project environment. This ensures `uv run` can be used to run arbitrary scripts or commands in your project environment. This ensures
@ -162,8 +161,8 @@ $ python example.py
The virtual environment must be active to run scripts and commands in the project without `uv run`. Virtual environment activation differs per shell and platform. The virtual environment must be active to run scripts and commands in the project without `uv run`. Virtual environment activation differs per shell and platform.
See the documentation on [running commands](../concepts/projects.md#running-commands) and [running See the documentation on [running commands](../concepts/projects.md#running-commands) and
scripts](../concepts/projects.md#running-scripts) in projects for more details. [running scripts](../concepts/projects.md#running-scripts) in projects for more details.
## Next steps ## Next steps

10
docs/guides/scripts.md
View file

@ -108,8 +108,8 @@ the project's dependencies. To opt-out of this behavior, use the `--no-project`
## Declaring script dependencies ## Declaring script dependencies
Python recently added a standard format for [inline script Python recently added a standard format for
metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata). [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. 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 To use inline script metadata, include a `script` section at the top of the script and declare the
@ -162,9 +162,9 @@ 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 uv will fetch the required Python version if it is not installed — see the documentation on
versions](../concepts/python-versions.md) for more details. Note that the `dependencies` field must [Python versions](../concepts/python-versions.md) for more details. Note that the `dependencies`
be provided even if empty. 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 Note that when using inline script metadata, even if `uv run` is used in a _project_, the project's
dependencies will be ignored. The `--no-project` flag is not required. dependencies will be ignored. The `--no-project` flag is not required.

4
docs/guides/tools.md
View file

@ -103,8 +103,8 @@ $ uv tool install ruff
``` ```
When a tool is installed, its executables are placed in a `bin` directory in the `PATH` which allows 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 the tool to be run without uv. If it's not on the `PATH`, a warning will be displayed and
update-shell` can be used to add it to the `PATH`. `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:

16
docs/index.md
View file

@ -18,10 +18,10 @@ 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 - ❇️ [Runs scripts](./guides/scripts.md), with support for
metadata](./guides/scripts.md#declaring-script-dependencies). [inline dependency metadata](./guides/scripts.md#declaring-script-dependencies).
- 🗂️ Provides [comprehensive project management](./guides/projects.md), with a [universal - 🗂️ Provides [comprehensive project management](./guides/projects.md), with a
lockfile](./concepts/projects.md#lockfile). [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` and - ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip` and
@ -47,8 +47,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 Then, check out the [first steps](./first-steps.md), see more
methods](./installation.md), or read on for a brief overview. [installation methods](./installation.md), or read on for a brief overview.
## Project management ## Project management
@ -77,7 +77,7 @@ See the [project guide](./guides/projects.md) to get started.
## Tool management ## Tool management
uv executes and installs command-line tools provided by Python packages, similar to `pipx`. uv executes and installs command-line tools provided by Python packages, similar to `pipx`.
Run a tool in an ephemeral environment with `uvx`: Run a tool in an ephemeral environment with `uvx`:
@ -143,7 +143,7 @@ $ uv run --python pypy@3.8 -- python --version
Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30) Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin [PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information. Type "help", "copyright", "credits" or "license" for more information.
>>>> >>>>
``` ```
Use a specific Python version in the current directory: Use a specific Python version in the current directory:

6
docs/installation.md
View file

@ -67,7 +67,7 @@ pip install uv
!!! note !!! note
There are prebuilt distributions (wheels) for many platforms; if not available for a given 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 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) [contributing setup guide](https://github.com/astral-sh/uv/blob/main/CONTRIBUTING.md#setup)
for details on building uv from source. for details on building uv from source.
@ -89,8 +89,8 @@ See our guide on [using uv in Docker](./guides/integration/docker.md) for more d
## GitHub Releases ## GitHub Releases
uv release artifacts can be downloaded directly from [GitHub uv release artifacts can be downloaded directly from
Releases](https://github.com/astral-sh/uv/releases). [GitHub Releases](https://github.com/astral-sh/uv/releases).
Each release page includes binaries for all supported platforms as well as instructions for using 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`. the standalone installer via `github.com` instead of `astral.sh`.

39
docs/pip/compatibility.md
View file

@ -3,8 +3,8 @@
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 `pip making meaningful changes to their packaging workflows; and, in most cases, swapping out
install` for `uv pip install` should "just work". `pip install` for `uv pip install` should "just work".
However, uv is _not_ intended to be an _exact_ clone of `pip`, and the further you stray from common However, uv is _not_ intended to be an _exact_ clone of `pip`, and the further you stray from common
`pip` workflows, the more likely you are to encounter differences in behavior. In some cases, those `pip` workflows, the more likely you are to encounter differences in behavior. In some cases, those
@ -57,10 +57,10 @@ package. `pip`, meanwhile, _may_ respect pre-release identifiers in transitive d
depending on the order in which the resolver encounters the relevant specifiers depending on the order in which the resolver encounters the relevant specifiers
([#1641](https://github.com/astral-sh/uv/issues/1641#issuecomment-1981402429)). ([#1641](https://github.com/astral-sh/uv/issues/1641#issuecomment-1981402429)).
Pre-releases are [notoriously Pre-releases are
difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to model, and are a [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to
frequent source of bugs in packaging tools. Even `pip`, which is viewed as a reference model, and are a frequent source of bugs in packaging tools. Even `pip`, which is viewed as a
implementation, has a number of open questions around pre-release handling reference implementation, has a number of open questions around pre-release handling
([#12469](https://github.com/pypa/pip/issues/12469), ([#12469](https://github.com/pypa/pip/issues/12469),
[#12470](https://github.com/pypa/pip/issues/12470), [#12470](https://github.com/pypa/pip/issues/12470),
[#40505](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/20), etc.). [#40505](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/20), etc.).
@ -68,10 +68,9 @@ uv's pre-release handling is _intentionally_ limited and _intentionally_ require
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
cover "dependency [do not cover "dependency resolution"](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/17)
resolution"](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/17) and and are instead focused on behavior for a _single_ version specifier. As such, there are unresolved
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.
@ -121,16 +120,18 @@ a match. This means that if a package exists on multiple indexes, uv will limit
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 version `pip`, meanwhile, will combine the candidate versions from all indexes, and select the best version
from the combined set, though it makes [no guarantees around the from the combined set, though it makes
order](https://github.com/pypa/pip/issues/5045#issuecomment-369521345) in which it searches indexes, [no guarantees around the order](https://github.com/pypa/pip/issues/5045#issuecomment-369521345) in
and expects that packages are unique up to name and version, even across indexes. which it searches indexes, and expects that packages are unique up to name and version, even across
indexes.
uv's behavior is such that if a package exists on an internal index, it should always be installed 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` package. See, for example,
attack](https://pytorch.org/blog/compromised-nightly-dependency/) from December 2022. [the `torchtriton` attack](https://pytorch.org/blog/compromised-nightly-dependency/) from
December 2022.
As of v0.1.39, users can opt in to `pip`-style behavior for multiple indexes via the As of v0.1.39, users can opt in to `pip`-style behavior for multiple indexes via the
`--index-strategy` command-line option, or the `UV_INDEX_STRATEGY` environment variable, which `--index-strategy` command-line option, or the `UV_INDEX_STRATEGY` environment variable, which
@ -148,8 +149,8 @@ While `unsafe-best-match` is the closest to `pip`'s behavior, it exposes users t
"dependency confusion" attacks. "dependency confusion" attacks.
In the future, uv will support pinning packages to dedicated indexes (see: In the future, uv will support pinning packages to dedicated indexes (see:
[#171](https://github.com/astral-sh/uv/issues/171)). Additionally, [PEP [#171](https://github.com/astral-sh/uv/issues/171)). Additionally,
708](https://peps.python.org/pep-0708/) is a provisional standard that aims to address the [PEP 708](https://peps.python.org/pep-0708/) is a provisional standard that aims to address the
"dependency confusion" issue across package registries and installers. "dependency confusion" issue across package registries and installers.
## Transitive direct URL dependencies for constraints and overrides ## Transitive direct URL dependencies for constraints and overrides
@ -188,8 +189,8 @@ In other words, uv inverts the default, requiring explicit opt-in to installing
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 For more, see
environments"](./environments.md#using-arbitrary-python-environments). ["Using arbitrary Python environments"](./environments.md#using-arbitrary-python-environments).
## Resolution strategy ## Resolution strategy

4
docs/pip/compile.md
View file

@ -84,8 +84,8 @@ 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 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 `requirements.txt` files with `uv pip install`. See the documentation on
files](packages.md#installing-packages-from-files) for more details. [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 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 unless they conflict with the lockfile. This means that the environment can have dependencies that

10
docs/pip/dependencies.md
View file

@ -29,12 +29,12 @@ cli = [
``` ```
Each of the keys defines an "extra", which can be installed using the `--extra` and `--all-extras` 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 flags or `package[<extra>]` syntax. See the documentation on
packages](./packages.md#installing-packages-from-files) for more details. [installing packages](./packages.md#installing-packages-from-files) for more details.
See the official [`pyproject.toml` See the official
guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for
getting started with a `pyproject.toml`. more details on getting started with a `pyproject.toml`.
## Using `requirements.in` ## Using `requirements.in`

17
docs/pip/environments.md
View file

@ -65,9 +65,9 @@ regardless of where uv is installed. Note that if `VIRTUAL_ENV` is set to a dire
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 provided to `uv pip sync` or `uv pip install`. For example,
--python /path/to/python` will install into the environment linked to the `/path/to/python` `uv pip install --python /path/to/python` will install into the environment linked to the
interpreter. `/path/to/python` interpreter.
For convenience, `uv pip install --system` will install into the system Python environment. Using For convenience, `uv pip install --system` will install into the system Python environment. Using
`--system` is roughly equivalent to `uv pip install --python $(which python)`, but note that `--system` is roughly equivalent to `uv pip install --python $(which python)`, but note that
@ -85,10 +85,9 @@ 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 of Python on Debian prior to Python 3.10 is unsupported due to the
`distutils` (but not [distribution's patching of `distutils` (but not `sysconfig`)](https://ffy00.github.io/blog/02-python-debian-and-the-install-locations/).
`sysconfig`)](https://ffy00.github.io/blog/02-python-debian-and-the-install-locations/). While we While we always recommend the use of virtual environments, uv considers them to be required in these
always recommend the use of virtual environments, uv considers them to be required in these
non-standard environments. non-standard environments.
If uv is installed in a Python environment, e.g., with `pip`, it can still be used to modify other If uv is installed in a Python environment, e.g., with `pip`, it can still be used to modify other
@ -124,5 +123,5 @@ included:
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 _require_ a virtual environment. Instead, it needs a Python toolchain to create ephemeral
environments. See the documentation on [toolchain environments. See the documentation on
discovery](../concepts/python-versions.md#discovery-order) for details on discovery. [toolchain discovery](../concepts/python-versions.md#discovery-order) for details on discovery.

13
docs/platforms.md
View file

@ -8,11 +8,12 @@ uv has Tier 1 support for the following platforms:
- Windows (x86_64) - Windows (x86_64)
uv is continuously built, tested, and developed against its Tier 1 platforms. Inspired by the Rust uv is continuously built, tested, and developed against its Tier 1 platforms. Inspired by the Rust
project, Tier 1 can be thought of as ["guaranteed to project, Tier 1 can be thought of as
work"](https://doc.rust-lang.org/beta/rustc/platform-support.html). ["guaranteed to work"](https://doc.rust-lang.org/beta/rustc/platform-support.html).
uv has Tier 2 support (["guaranteed to uv has Tier 2 support
build"](https://doc.rust-lang.org/beta/rustc/platform-support.html)) for the following platforms: (["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)
@ -27,7 +28,7 @@ or developed against, and so stability may vary in practice.
Beyond the Tier 1 and Tier 2 platforms, uv is known to build on i686 Windows, and known _not_ to Beyond the Tier 1 and Tier 2 platforms, uv is known to build on i686 Windows, and known _not_ to
build on aarch64 Windows, but does not consider either platform to be supported at this time. The build on aarch64 Windows, but does not consider either platform to be supported at this time. The
minimum supported Windows version is Windows 10, following [Rust's own Tier 1 minimum supported Windows version is Windows 10, following
support](https://blog.rust-lang.org/2024/02/26/Windows-7.html). [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.

3
scripts/packages/README.md
View file

@ -1,3 +1,4 @@
# packages # packages
A collection of packages used to test editable installs and bespoke behaviors in packaging setups and definitions. A collection of packages used to test editable installs and bespoke behaviors in packaging setups
and definitions.