## Summary
Adds note to docs about PEP 751 to documentation as discussed in #12641
## Test Plan
Previewed locally
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
Add an option to overwrite the list of available Python downloads from a
local JSON file by using the environment variable
`UV_PYTHON_DOWNLOADS_JSON_URL`
as an experimental support for providing custom sources for Python
distribution binaries #8015
related #10203
I probably should make the JSON to be fetched from a remote URL instead
of a local file.
please let me know what you think and I will modify the code
accordingly.
## Test Plan
### normal run
```
root@75c66494ba8b:/# /code/target/release/uv python list
cpython-3.14.0a4+freethreaded-linux-x86_64-gnu <download available>
cpython-3.14.0a4-linux-x86_64-gnu <download available>
cpython-3.13.1+freethreaded-linux-x86_64-gnu <download available>
cpython-3.13.1-linux-x86_64-gnu <download available>
cpython-3.12.8-linux-x86_64-gnu <download available>
cpython-3.11.11-linux-x86_64-gnu <download available>
cpython-3.10.16-linux-x86_64-gnu <download available>
cpython-3.9.21-linux-x86_64-gnu <download available>
cpython-3.8.20-linux-x86_64-gnu <download available>
cpython-3.7.9-linux-x86_64-gnu <download available>
pypy-3.10.14-linux-x86_64-gnu <download available>
pypy-3.9.19-linux-x86_64-gnu <download available>
pypy-3.8.16-linux-x86_64-gnu <download available>
pypy-3.7.13-linux-x86_64-gnu <download available>
```
### empty JSON file
```sh
root@75c66494ba8b:/# export UV_PYTHON_DOWNLOADS_JSON_URL=/code/crates/uv-python/my-download-metadata.json
root@75c66494ba8b:/# cat $UV_PYTHON_DOWNLOADS_JSON_URL
{}
root@75c66494ba8b:/# /code/target/release/uv python list
root@75c66494ba8b:/#
```
### JSON file with valid version
```sh
root@75c66494ba8b:/# export UV_PYTHON_DOWNLOADS_JSON_URL=/code/crates/uv-python/my-download-metadata.json
root@75c66494ba8b:/# cat $UV_PYTHON_DOWNLOADS_JSON_URL
{
"cpython-3.11.9-linux-x86_64-gnu": {
"name": "cpython",
"arch": {
"family": "x86_64",
"variant": null
},
"os": "linux",
"libc": "gnu",
"major": 3,
"minor": 11,
"patch": 9,
"prerelease": "",
"url": "https://github.com/astral-sh/python-build-standalone/releases/download/20240814/cpython-3.11.9%2B20240814-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz",
"sha256": "daa487c7e73005c4426ac393273117cf0e2dc4ab9b2eeda366e04cd00eea00c9",
"variant": null
}
}
root@75c66494ba8b:/# /code/target/release/uv python list
cpython-3.11.9-linux-x86_64-gnu <download available>
root@75c66494ba8b:/#
```
### Remote Path
```sh
root@75c66494ba8b:/# export UV_PYTHON_DOWNLOADS_JSON_URL=http://a.com/file.json
root@75c66494ba8b:/# /code/target/release/uv python list
error: Remote python downloads JSON is not yet supported, please use a local path (without `file://` prefix)
```
---------
Co-authored-by: Aria Desires <aria.desires@gmail.com>
@jtfmumm mentioned a desire for this. I'm not sure how we should do
this. I kind of want to change this to something like...
```
$ uv python find
CPython 3.13 @ <path>
$ uv python find --only-path
<path>
$ uv python find --short
<path>
$ uv python find --only-version
3.13
```
The change in defaults would be breaking though.
## Summary
Fix a suggestion in the docs on configs through environment variables,
which lists an option value that doesn't appear to exist.
The description implies that `unsafe-best-match` was intended here.
## Test Plan
Verified by providing `unsafe-any-match` as a parameter to `uv`. It
didn't error, but appeared to use the `first-index` strategy instead.
The value I changed it to behaves as described by the documentation.
Fix broken grammar and hl_lines.
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
Some simple doc fixes.
<!-- What's the purpose of the change? What does it do, and why? -->
## Test Plan
N/A
<!-- How was it tested? -->
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
Support the `UV_PROJECT` environment variable to set the project
directory.
#11946
## Test Plan
<!-- How was it tested? -->
`cargo nextest run` passed except the cache_prune.
```
export UV_PROJECT=/path/to/project
uv sync
```
works.
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
## Summary
I only changed the location of where the fish completions get sent, from
`~/.config/fish/config.fish` to `~/.config/fish/completions/uv.fish` and
`~/.config/fish/completions/uvx.fish` respectively
## Test Plan
I have tested and putting the completions in those paths works fine and
complies with the fish docs. Also keeps your `config.fish` clean
### edit:
refer to
https://fishshell.com/docs/current/completions.html#where-to-put-completions
> This wide search may be confusing. If you are unsure, your completions
probably belong in `~/.config/fish/completions`.
Adding dependency trace/parent comments ("via ...") to the export
command output.
This is a similar behavior to the pip compile output.
#### Note to the eager reviewer:
First of all - thanks!
Secondly, this is still a very rough draft. These are the first lines of
code I've ever written in Rust. This is still mostly an educational/fun
exercise for myself. If opening a Draft PR is creating too much noise -
I apologize and I will close it until it is ready.
## Summary
Resolves#7777
## Test Plan
- [X] manual command execution
- [x] update expected output in tests
---------
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
The idea here is that we introduce a new stdout_important method for
things that want to care about the difference between "quiet" and
"silent".
This PR is WIP because it has no actual uses of stdout_important, and we
should have at least one before landing this. Perhaps someone has a
suggestion for commands that would really benefit from this distinction?
Fixes#10431
## Summary
This PR extends `[[tool.uv.index]]` to support `--find-links`-style
"flat" indexes, so that users can point to such indexes without using
`--find-links` _and_ get access to the full functionality of
`[[tool.uv.index]]` (e.g., they can now pin packages to
`--find-links`-style indexes).
Note that, at present, `--find-links` indexes actually have some quirky
behavior, in that we combine them into a single entity and then merge
the discovered distributions into each Simple API-style index. The
motivation here, IIRC, was to match pip's behavior quite closely. I'm
interested in _removing_ that behavior, but it'd be breaking (and may
also be inconvenient for some use-cases). So, the behavior for indexes
passed in via `--find-links` remains completely unchanged. However,
`[[tool.uv.index]]` entries with `format = "flat"` are now treated
identically to those defined with `format = "simple"` (the default), in
that we stop after we find the first-matching index, etc.
Closes https://github.com/astral-sh/uv/issues/11634.
## Summary
This fixes https://github.com/astral-sh/uv/issues/12426 which helps use
a more accurate arg name in the help output.
## Test Plan
I didn't test it locally, @charliermarsh gave me guidance on what to
change so I looked around that file for another example of `value_name`
and repeated what I saw. I kept it formatted to 1 line based on it not
being a long line. The other example of `value_name` had everything on
separate lines because there were a bunch of parameters passed in.
---------
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
Allows `uv python list <request>` to filter the installed list. I often
want this and it's not hard to add.
I tested the remote download filtering locally (#12381 is needed for
snapshot tests)
```
❯ cargo run -q -- python list --all-versions 3.13
cpython-3.13.2-macos-aarch64-none <download available>
cpython-3.13.1-macos-aarch64-none /opt/homebrew/opt/python@3.13/bin/python3.13 -> ../Frameworks/Python.framework/Versions/3.13/bin/python3.13
cpython-3.13.1-macos-aarch64-none <download available>
cpython-3.13.0-macos-aarch64-none /Users/zb/.local/share/uv/python/cpython-3.13.0-macos-aarch64-none/bin/python3.13
❯ cargo run -q -- python list --all-versions 3.13 --only-installed
cpython-3.13.1-macos-aarch64-none /opt/homebrew/opt/python@3.13/bin/python3.13 -> ../Frameworks/Python.framework/Versions/3.13/bin/python3.13
cpython-3.13.0-macos-aarch64-none /Users/zb/.local/share/uv/python/cpython-3.13.0-macos-aarch64-none/bin/python3.13
```
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
Fixes#12334
<!-- What's the purpose of the change? What does it do, and why? -->
## Test Plan
<!-- How was it tested? -->
## Summary
Resolves#11794.
When `uv python find` is given a `--script` option, either the existing
environment for that script or the Python executable that would be used
to create it will be returned. If neither are found, the command exits
with exit code 1.
`--script` is incompatible with all other options to the same command.
## Test Plan
Unit tests.
## Summary
This is a prototype that I'm considering shipping under `--preview`,
based on [`light-the-torch`](https://github.com/pmeier/light-the-torch).
`light-the-torch` patches pip to pull PyTorch packages from the PyTorch
indexes automatically. And, in particular, `light-the-torch` will query
the installed CUDA drivers to determine which indexes are compatible
with your system.
This PR implements equivalent behavior under `--torch-backend auto`,
though you can also set `--torch-backend cpu`, etc. for convenience.
When enabled, the registry client will fetch from the appropriate
PyTorch index when it sees a package from the PyTorch ecosystem (and
ignore any other configured indexes, _unless_ the package is explicitly
pinned to a different index).
Right now, this is only implemented in the `uv pip` CLI, since it
doesn't quite fit into the lockfile APIs given that it relies on feature
detection on the currently-running machine.
## Test Plan
On macOS, you can test this with (e.g.):
```shell
UV_TORCH_BACKEND=auto UV_CUDA_DRIVER_VERSION=450.80.2 cargo run \
pip install torch --python-platform linux --python-version 3.12
```
On a GPU-enabled EC2 machine:
```shell
ubuntu@ip-172-31-47-149:~/uv$ UV_TORCH_BACKEND=auto cargo run pip install torch -v
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
Running `target/debug/uv pip install torch -v`
DEBUG uv 0.6.6 (e95ca063b 2025-03-14)
DEBUG Searching for default Python interpreter in virtual environments
DEBUG Found `cpython-3.13.0-linux-x86_64-gnu` at `/home/ubuntu/uv/.venv/bin/python3` (virtual environment)
DEBUG Using Python 3.13.0 environment at: .venv
DEBUG Acquired lock for `.venv`
DEBUG At least one requirement is not satisfied: torch
warning: The `--torch-backend` setting is experimental and may change without warning. Pass `--preview` to disable this warning.
DEBUG Detected CUDA driver version from `/sys/module/nvidia/version`: 550.144.3
...
```
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
The examples assume that the packages are in the project root directory.
However, they are nested inside `src`, and the commands in the examples
do not work as intended.
I could not find any related issues.
## Test Plan
<!-- How was it tested? -->
I tested it by executing the commands on my terminal - Linux and Windows
(PowerShell).
---------
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
Currently, for users to specify at the command line whether to use
uv-managed or system Python interpreters, they use the
`--python-preference` parameter, which takes four possible values. This
is more complex than necessary since the normal case is to either say
"only managed" or "not managed". This PR hides the old
`--python-preference` parameter from help and documentation and adds two
new flags: `--managed-python` and `--no-managed-python` to capture the
"only managed" and "not managed" cases.
I have successfully tested this locally but currently cannot add
snapshot tests because of problems with distinguishing managed vs.
system interpreters in CI (and non-determinism when run on different
developers' machines). The `--python-preference` test in
`tool-install.rs` is currently ignored for this reason. See #5144 and
#7473.
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
This has come up a few times, so it seems worth addressing. If you
migrate from a flat layout to a `src` layout or vice versa, we now
invalidate the package metadata.
Closes https://github.com/astral-sh/uv/issues/12047
## Summary
This ended up being more involved than expected. The gist is that we
setup all the packages we want to reinstall upfront (they're passed in
on the command-line); but at that point, we don't have names for all the
packages that the user has specified. (Consider, e.g., `uv pip install
.` -- we don't have a name for `.`, so we can't add it to the list of
`Reinstall` packages.)
Now, `Reinstall` also accepts paths, so we can augment `Reinstall` based
on the user-provided paths.
Closes#12038.
This is a minimal redux of #10861 to be compatible with `uv pip`.
This implements the interface described in:
https://github.com/pypa/pip/pull/13065#issuecomment-2544000876 for `uv
pip install` and `uv pip compile`. Namely `--group <[path:]name>`, where
`path` when not defined defaults to `pyproject.toml`.
In that interface they add `--group` to `pip install`, `pip download`,
and `pip wheel`. Notably we do not define `uv pip download` and `uv pip
wheel`, so for parity we only need to implement `uv pip install`.
However, we also support `uv pip compile` which is not part of pip
itself, and `--group` makes sense there too.
----
The behaviour of `--group` for `uv pip` commands makes sense for the
cases upstream pip supports, but has confusing meanings in cases that
only we support (because reading pyproject.tomls is New Tech to them but
heavily supported by us). **Specifically case (h) below is a concerning
footgun, and case (e) below may get complaints from people who aren't
well-versed in dependency-groups-as-they-pertain-to-wheels.**
## Only Group Flags
Group flags on their own work reasonably and uncontroversially, except
perhaps that they don't do very clever automatic project discovery.
a) `uv pip install --group path/to/pyproject.toml:mygroup` pulls up
`path/to/project.toml` and installs all the packages listed by its
`mygroup` dependency-group (essentially treating it like another kind of
requirements.txt). In this regard it functions similarly to
`--only-group` in the rest of uv's interface.
b) `uv pip install --group mygroup` is just sugar for `uv pip install
--group pyproject.toml:mygroup` (**note that no project discovery
occurs**, upstream pip simply hardcodes the path "pyproject.toml" here
and we reproduce that.)
c) `uv pip install --group a/pyproject.toml:groupx --group
b/pyproject.toml:groupy`, and any other instance of multiple `--group`
flags, can be understood as completely independent requests for the
given groups at the given files.
## Groups With Named Packages
Groups being mixed with named packages also work in a fairly
unsurprising way, especially if you understand that things like
dependency-groups are not really supposed to exist on pypi, they're just
for local development.
d) `uv pip install mypackage --group path/to/pyproject.toml:mygroup`
much like multiple instances of `--group` the two requests here are
essentially completely independent: pleases install `mypackage`, and
please also install `path/to/pyproject.toml:mygroup`.
e) `uv pip install mypackage --group mygroup` is exactly the same, but
this is where it becomes possible for someone to be a little confused,
as you might think `mygroup` is supposed to refer to `mypackage` in some
way (it can't). But no, it's sourcing `pyproject.toml:mygroup` from the
current working directory.
## Groups With Requirements/Sourcetrees/Editables
Requirements and sourcetrees are where I expect users to get confused.
It behaves *exactly* the same as it does in the previous sections but
you would absolutely be forgiven for expecting a different behaviour.
*Especially* because `--group` with the rest of uv *does* do something
different.
f) `uv pip install -r a/pyproject.toml --group b/pyproject.toml:mygroup`
is again just two independent requests (install `a/pyproject.toml`'s
dependencies, and `b/pyproject.toml`'s `mygroup`).
g) `uv pip install -r pyproject.toml --group mygroup` is exactly like
the previous case but *incidentally* the two requests refer to the same
file. What the user wanted to happen is almost certainly happening, but
they are likely getting "lucky" here that they're requesting something
simple.
h) `uv pip install -r a/pyproject.toml --group mygroup` is again exactly
the same but the user is likely to get surprised and upset as this
invocation actually sources two different files (install
`a/pyproject.toml`'s dependencies, and `pyproject.toml`'s `mygroup`)! I
would expect most people to assume the `--group` flag here is covering
all applicable requirements/sourcetrees/editables, but no, it continues
to be a totally independent reference to a file with a hardcoded
relative path.
------
Fixes https://github.com/astral-sh/uv/issues/8590
Fixes https://github.com/astral-sh/uv/issues/8969
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
Update this example snippet adding test.pypi.org as a publishing index
to mark the index with `explicit = true`. This will help prevent users
from unexpected behavior if no other indices are defined and users don't
select a different index selection algorithm (with `--index-strategy`).
When `test.pypi.org` is the selected index for package management,
packages resolve to odd versions like 0.0.1 and `uv` spits out lots of
errors.
<!-- What's the purpose of the change? What does it do, and why? -->
## Test Plan
N/A, documentation only change
<!-- How was it tested? -->
These changes add support for
```
uv python pin 3.12 --global
```
This adds the specified version to a `.python-version` file in the
user-level config directory. uv will now use the user-level version as a
fallback if no version is found in the project directory or its
ancestors.
Closes#4972
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
The command `uv python find >=3.11` doesn't work . The version should be
quoted otherwise the terminal interprets the `>` and pipes output to a
file named `=3.11`. I've used single quotes as used on line 90 of this
file.
## Test Plan
Locally
## Summary
Follow up to https://github.com/astral-sh/uv/pull/11888 with added
support for uv tool run.
Changes
* Added functionality for running windows scripts in previous PR was
moved from run.rs to uv_shell::runnable.
* EXE was added as a supported type, this simplified integration across
both uv run and uvx while retaining a backwards compatible behavior and
properly prioritizing .exe over others. Name was adjusted to runnable as
a result to better represent intent.
## Test Plan
New tests added.
## Documentation
Added new documentation.
Adds a new optional key `auth-policy` to `[tool.uv.index]` that sets the
authentication policy for the index URL.
The default is `"auto"`, which attempts to authenticate when necessary.
`"always"` always attempts to authenticate and fails if the endpoint is
unauthenticated. `"never"` never attempts to authenticate.
These policy address two kinds of cases:
* Some indexes don’t fail on unauthenticated requests; instead they just
forward to the public PyPI. This can leave the user confused as to why
their package is missing. The "always" policy prevents this.
* "never" allows users to ensure their credentials couldn't be leaked to
an unexpected index, though it will only allow for successful requests
on an index that doesn't require credentials.
Closes#11600
## Summary
In https://github.com/astral-sh/uv/issues/11998, a user is attempting to
vendor `pydantic-core`. But when they add `pydantic-core = { path =
"src/foo/vendor/pydantic-core" } `, we're installing it as a virtual
package, since `pydantic-core/pyproject.toml` contains `package =
false`.
This PR allows users to mark dependencies as "explicitly a package" or
"explicitly not a package" (i.e., virtual), as a workaround.
Closes https://github.com/astral-sh/uv/issues/11998.
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
Similar to https://github.com/astral-sh/uv/pull/11399
This adds `UV_NO_BUILD` and `UV_NO_BUILD_PACKAGE` environment variables
for non-pip commands.
## Test Plan
<!-- How was it tested? -->
Tested manually and with snapshot tests.
Fixes#11963
Signed-off-by: Alex Lowe <alex@lowe.dev>
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
## Test Plan
<!-- How was it tested? -->
## Summary
This is roughly equivalent, but gets the non-`+cpu` macOS build from the
PyTorch index rather than PyPI. It seems a bit simpler? Though up for
debate.
## Summary
The current wording on the [caching
page](https://docs.astral.sh/uv/concepts/cache/#dynamic-metadata) makes
it sounds like defining `cache-keys` in a project adds to the metadata
considered when caching. However it actually replaces the metadata. So
copying the example using the git commit results in only considering the
git commit, not the pyproject.toml, which is likely not what is
typically desired.
---------
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
Reworks how log verbosity flags work.
* `<no argument>` is the same, equivalent to `RUST_LOG=off`
* `-v` is the same, equivalent to `RUST_LOG=uv=debug`
* `-vv` is now equivalent to `RUST_LOG=uv=trace` (previously it only
enabled more log message context)
* `-vvv` is now equivalent to `RUST_LOG=trace` (previously it was
equivalent to `-vv`)
The "more context" that `-vv` had has been moved to an orthogonal
setting via an environment variable. Setting `UV_LOG_CONTEXT=1` will add
the extra context that `-vv` did.
In the future we may make these more granular as we try to use
`info!/warn!` more.
Fixes#1569
I need to self-review this still.
Updates the "Locking and syncing" page to actually have content on
syncing — which was the original intent, the rest of this file was just
copied out of the "Projects" page when I split it into multiple pages.
---------
Co-authored-by: Ed Morley <501702+edmorley@users.noreply.github.com>
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
## Summary
Closes#9867.
Update alternative indexes documentation to use `[[tool.uv.index]]` and
the associated environment variables instead of `UV_INDEX`.
This also globally reworks the documentation by:
- adding AWS CodeArtifact keyring example
- adding packages publishing examples for all providers
- making it more consistent for all providers
It might be best to show how to publish packages only once for all
providers, but the publish URL usually being different than the URL used
to retrieve packages, even if this duplicates things, it might still be
more straightforward for users to see exactly what is needed for each
provider.
## Test Plan
Manually tested retrieving packages from AWS CodeArtifact and GCP
Artifact Registry using both token and keyring.
Could not test:
- Publishing packages
- Azure Artifacts (not using it at all)
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
Fixes readme typo in syntax of environments in `pyproject.toml`
## Test Plan
<!-- How was it tested? -->
n/a
Revert #11601 for now
We run Python interpreter discovery with `-I` (#2500) which means these
environments variables are ignored when determining `sys.path`. Unless
we decide to remove the `-I` flag from the `sys.path` query, we
shouldn't release these changes to interpreter discovery caching.
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
Just to add the section for installing and upgrading uv tool, specifying
the Python version, in the document.
Originally, it was planned to add a markdown block (header) for
representation, but it was felt to be a bit redundant, so it ended up
being like this.
close https://github.com/astral-sh/uv/issues/11536
## Test Plan
Run doc server with strict mode in local. (``mkdocs serve -f
mkdocs.public.yml --strict``)
<!-- How was it tested? -->
---------
Signed-off-by: FishAlchemist <48265002+FishAlchemist@users.noreply.github.com>
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
When tests are run downstream, the `COLUMNS` environment variable is
used to force fixed output width and avoid test failures due to
different terminal widths. However, this occasionally causes test
regressions when other tests rely on different output width. Use the
same `COLUMNS` value in CI to ensure consistent output and catch any
regressions.
## Test Plan
It wasn't, it's supposed to be tested by the CI :-).
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
Resolves#6913.
Add `tool.uv.build-constraint-dependencies` to pyproject.toml.
The changes are analogous to the constraint-dependencies feature
implemented in #5248.
Add documentation for `build-constraint-dependencies`
## Test Plan
Add tests for `uv lock`, `uv add`, `uv pip install` and `uv pip
compile`.
---------
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
## Summary
This PR revives https://github.com/astral-sh/uv/pull/10017, which might
be viable now that we _don't_ enforce any platforms by default.
The basic idea here is that users can mark certain platforms as required
(empty, by default). When resolving, we ensure that the specified
platforms have wheel coverage, backtracking if not.
For example, to require that we include a version of PyTorch that
supports Intel macOS:
```toml
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["torch>1.13"]
[tool.uv]
required-platforms = [
"sys_platform == 'darwin' and platform_machine == 'x86_64'"
]
```
Other than that, the forking is identical to past iterations of this PR.
This would give users a way to resolve the tail of issues in #9711, but
with manual opt-in to supporting specific platforms.
Initially it seemed like `app.py` might be slightly more desirable but
people seem to overwhelmingly favour `main.py` as a good "generic" name.
Fixes#7782
Closes#11285
Closes https://github.com/astral-sh/uv/pull/11437
This changes `-p` from an alias of `--python-version` to `--python`
while retaining backwards compatibility for `--python-version`-like
fallback behavior when the requested version, e.g., `-p 3.12`, cannot be
found.
This was initially implemented with a hidden `--python-legacy` flag
which allows us to special case the short `-p` flag — unlike the
implementation in #11437. However, after further discussion, we decided
the behavior difference between `-p` and `--python` would be confusing
so now `-p` is an alias for `--python` and `--python` is special-cased
when a version is used.
Additionally, we now respect the `UV_PYTHON` environment variable, but
it is ignored when `--python-version` is set. If you want different
`--python-version` and `--python` values, you must do so explicitly. I
considered banning this, but it is valid for e.g. `--python pypy
--python-version 3.12`
Unlike https://github.com/astral-sh/uv/pull/10222, this does not respect
`UV_PYTHON` in `uv python uninstall` (continuing to require an explicit
target there) which I think is simpler and matches our `.python-version`
file behavior.
---------
Co-authored-by: Choudhry Abdullah <cabdulla@trinity.edu>
Co-authored-by: Choudhry Abdullah <choudhry347@choudhrys-air-2.trinity.local>
Co-authored-by: Aria Desires <aria.desires@gmail.com>
## Summary
The environment is located at a stable path within the cache, based on
the script's absolute path.
If a lockfile exists for the script, then we use our standard lockfile
semantics (i.e., update the lockfile if necessary, etc.); if not, we
just do a `uv pip sync` (roughly).
Example usage:
```
❯ uv init --script hello.py
Initialized script at `hello.py`
❯ uv add --script hello.py requests
Updated `hello.py`
❯ cargo run sync --script hello.py
Using script environment at: /Users/crmarsh/.cache/uv/environments-v1/hello-84e289fe3f6241a0
Resolved 5 packages in 3ms
Installed 5 packages in 12ms
+ certifi==2025.1.31
+ charset-normalizer==3.4.1
+ idna==3.10
+ requests==2.32.3
+ urllib3==2.3.0
```
Closes https://github.com/astral-sh/uv/issues/6637.
## Summary
The [current scripts docs
page](https://docs.astral.sh/uv/guides/scripts/) doesn't include detail
on how to use a custom package index when setting up a script. I believe
this might be because it didn't use to work (see #6688 ) but it now does
(thanks for that, by the way! 😄)
Given it's a useful feature, I suggest adding a quick example to the
scripts page, with the details of authentication, etc. left to the main
`indexes.md` doc.
I'd also suggests that this closes#6688, though it doesn't actually add
that feature - that appears to have already been done :)
## Test Plan
No testing is needed, I think!
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
Use `UV_INDEX` instead of the deprecated `UV_EXTRA_INDEX_URL`.
<!-- What's the purpose of the change? What does it do, and why? -->
## Test Plan
It is a minor documentation change.
<!-- How was it tested? -->
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
This adds `NO_BINARY` and `NO_BINARY_PACKAGE` environment variables to
the uv CLI, allowing the user to specify packages to build from source
using environment variables. Its not a complete fix for #4291 as it does
not handle the `pip` subcommand.
## Test Plan
This was tested by running `uv sync` with various `UV_NO_BINARY` and
`UV_NO_BINARY_PACKAGE` environment variables set and checking that the
correct set of packages were compiled rather than taken from pre-built
wheels.
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
I've just fixed some broken anchors after browing ux doc site.
## Test Plan
- `index.md`: based on `mkdocs serve` log
- `readme.md`: manual check
## Aside
Do you manually keep `readme.md` and `index.md` partially sync? I've
tried
checking pre-commit and other scripts but found no way to port my edits
from one
to the other.
<!-- How was it tested? -->
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
I followed the docs to install flash-attn with uv and got the following
issue
```uv sync
Resolved 27 packages in 12ms
× Failed to build `flash-attn==2.7.4.post1`
├─▶ The build backend returned an error
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)
[stderr]
Traceback (most recent call last):
File "<string>", line 8, in <module>
ModuleNotFoundError: No module named 'setuptools'
hint: This usually indicates a problem with the package or the build environment.
```
installing setuptools before running uv sync as done with torch helps
fix it.
## Test Plan
I tested locally before it failed to install, after it worked
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
- PowerShell isn't Windows-only
- Bash/Elvish isn't UNIX-only
- PowerShell profile won't necessarily exist
- Extracted the `echo $SHELL` tip to a tip tooltip
The new PowerShell lines are taken directly from
https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.5#how-to-create-a-profile
Note that the "Standalone installer" commands are unaffected. Running
the Linux one through PowerShell worked just fine.
## Test Plan
Look at the page generated from this PR
<!-- How was it tested? -->
I think `UV_PROJECT_ENVIRONMENT` is too complicated for use-cases where
the user wants to sync to the active environment. I don't see a
compelling reason not to make opt-in easier. I see a lot of questions
about how to deal with this warning in the issue tracker, but it seems
painful to collect them here for posterity.
A notable behavior here — we'll treat this as equivalent to
`UV_PROJECT_ENVIRONMENT` so... if you point us to a valid virtual
environment that needs to be recreated for some reason (e.g., new Python
version request), we'll happily delete it and start over.
Since the resolver internals docs were written, we added a lot more
features to the resolver, which should be documented.
As usual, these docs are not targeted at regular users, but should give
interested readers an insight into the internals of uv and help advanced
users with especially hard resolver problems.
## Summary
It turns out activating the kernel does not change `VIRTUAL_ENV`, so we
still install into the environment the Jupyter environment, rather than
the project environment.
Unfortunately, after this change, we do still show a warning on `uv
add`:
```
warning: `VIRTUAL_ENV=/Users/crmarsh/.cache/uv/archive-v0/3bddKDdYXuX2w57Fu6itL` does not match the project environment path `.venv` and will be ignored
```
`uv pip install` works without warning.
Closes#11154.
We regularly get questions why `uv build` is missing certain files or
using the wrong build tag, when that's done by the build backend and
part of the build backend's docs. I tried to clarify this difference and
to redirect users to look at the tool's docs instead of wondering why
uv's docs don't explain that.
---------
Co-authored-by: Ed Morley <501702+edmorley@users.noreply.github.com>
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
Maybe slightly controversial because it's more verbose, but we really
want to limit these indexes to Linux and Windows, rather than ignoring
them on Darwin. E.g., we'd also want to ignore them on other platforms.
Further down, I use markers that look like this in the more complete
examples, so this feels more consistent.
This PR rewords the instructions for using uv in a container. I'm a new
user and was somewhat confused by it, so I've rewritten it as I'd have
liked to have read it.
It makes it more clear what distroless means, to avoid confusion with
other projects that ship OS files with an image with its tag name clear
of qualifiers(`astral-sh/uv`, in this case). An example of that is
caddy, which ships with alpine.
This also modifies the original example to use a distroful image instead
of distroless one while #8635 doesn't get resolved.
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
Fixes a recurring typo.
## Details
There's a typo appearing in a particular sentence...
> Ignore package dependencies, instead only add those packages
explicitly listed on the command line to the resulting **the**
requirements file.
... used in:
* `crates/uv-cli/src/lib.rs`
* `crates/uv-settings-src-settings.rs`
* `docs/reference/settings.md`
* `uv.schem.json`
Docs, comments and a CLI command description seem affected.
This PR fixes it.
---------
Co-authored-by: bujnok01 <bujnok01@heiway.net>
I'm not sure if this should go in the CLI reference or not? but here
seems like an okay start. I want to figure out a way to avoid repeating
this content.
I'm sorry, but I was writing some new content here and the inconsistent
wrapping was very hard to maintain and I didn't want to muddy the diff
there with reflowing.
I don't think we need to be strict about the reflow (I'm not sure we
even can be) but some of these were very far off from our typical wrap
length.
## Summary
The latter issue has been closed in favour of the former, so just link
the one issue Dependabot is using to track this.
## Test Plan
N/A
---
Thanks!
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
## Test Plan
<!-- How was it tested? -->
## Add activation commands for fish shell and other alternative shells
While trying to use uv with fish shell, I encountered an issue as
`source .venv/bin/activate` didn't work. The documentation didn't
specify that fish shell requires using `source .venv/bin/activate.fish`
instead. I created issue #10986 to address this.
This PR improves the documentation by:
- Adding the correct activation command for fish shell: `source
.venv/bin/activate.fish`
- Adding the correct activation command for Nushell: `use
.venv\Scripts\activate.nu`
- Adding the correct activation command for Tcsh: `use
.venv/bin/activate.csh`
This will help users of alternative shells to properly activate their
virtual environments without encountering the same confusion I
experienced.
Fixes#10986
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
As requested in https://github.com/astral-sh/uv/issues/6565, this adds a
tip discussing the ability to pin the image to a specific SHA digest and
why it may be useful.
## Test Plan
<!-- How was it tested? -->
Start serving the documentation locally
```shell
uvx --with-requirements docs/requirements.txt -- mkdocs serve -f mkdocs.public.yml
```
Then navigate to http://127.0.0.1:8000/uv/guides/integration/docker/ to
see the tool tip being rendered properly
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
We'll probably end up shipping but we were moving ahead with this on the
basis that pip may not even ship this, so let's play it safe and wait
for a bit.
Ultimately this is a lot of settings plumbing and a couple minor pieces
of Actual Logic (which are so simple I have to assume there's something
missing, but maybe not!).
Note this "needlessly" use DevDependencyGroup since it costs nothing, is
more futureproof, and lets us maintain one primary interface (we just
pass `false` for all the dev arguments).
Fixes#8590Fixes#8969
## Summary
Added missing `repos:` line to make the example config complete
---------
Co-authored-by: Rajesh Veeranki <rveeranki@d4q74qfn2y.agoda.local>
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
The docs did mention that you could set the `UV_PROJECT_ENVIRONMENT`
variable to point Uv to use the system Python environment (e.g. for use
in CI or Docker), but it did not document _how_.
Reference:
https://github.com/astral-sh/uv/pull/6834#issuecomment-2319253359
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
rooster should pick those up, but those 2 references were added to 0.5.8
while a 0.5.9 was already released
(f5add0ca5e),
so they never got bumped automatically.
I've searched for other cases like this in the documentation on other
versions, just in case, and it seems that this is the only case.
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
Fix invalid links in [configuring
projects](https://docs.astral.sh/uv/concepts/projects/config/#entry-points)
doc.
## Test Plan
<!-- How was it tested? -->
## Summary
Unless I'm doing something wrong, specifying `hatchling` as a build
system here results in `ValueError: Unable to determine which files to
ship`
## Test Plan
Following the instructions of the document.
## Additional
Don't hesitate to discard
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
I use `uv` for automation on remote hosts and it would be useful to have
it be able to tell me the supported versions of python (for the remote
machine) in a machine readable manner so I do not need to parse `uv
python list`.
This change adds `--format (json|text)` to `uv python list` to make it's
output machine readable
Loosely related:
- https://github.com/astral-sh/uv/issues/411
## Test Plan
Manually tested via
```
# quick inspection without pretty print
cargo run -- python list --format json
```
### Short example of output (trimmed down)
Cmd: `cargo run -- python list --format json | jq '.[:2]'`
```json
[
{
"key": "cpython-3.13.1+freethreaded-linux-x86_64-gnu",
"version": "3.13.1",
"version_parts": {
"major": 3,
"minor": 13,
"patch": 1
},
"path": null,
"symlink": null,
"url": "https://github.com/astral-sh/python-build-standalone/releases/download/20241219/cpython-3.13.1%2B20241219-x86_64-unknown-linux-gnu-freethreaded%2Bpgo%2Blto-full.tar.zst",
"os": "linux",
"variant": "freethreaded",
"implementation": "cpython",
"arch": "x86_64",
"libc": "gnu"
},
{
"key": "cpython-3.13.1-linux-x86_64-gnu",
"version": "3.13.1",
"version_parts": {
"major": 3,
"minor": 13,
"patch": 1
},
"path": "/usr/bin/python3.13",
"symlink": null,
"url": null,
"os": "linux",
"variant": "default",
"implementation": "cpython",
"arch": "x86_64",
"libc": "gnu"
}
]
```
---------
Co-authored-by: John Zlotek <jzlotek@gmail.com>
## Summary
Resolves#5952
Add a `--path` option to `uv pip freeze` to be compatible with `pip
freeze`
## Test Plan
New snapshot tests
---------
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
## Summary
Closes#3312.
This PR adds Git LFS support to the `uv-git` crate by using the
`git-lfs` CLI to fetch required LFS objects for a revision following the
call to `git fetch`.
The LFS fetch step is disabled by default and only enabled if the
environment variable `UV_GIT_LFS` is set.
When enabled, the LFS fetch step is run for all repositories regardless
of whether they have associated LFS objects. The step is skipped if the
`git-lfs` CLI tool isn't installed.
## Test Plan
I verified that the minimal example in the linked issue passes, i.e.
this command now succeeds:
```sh
UV_GIT_LFS=1 uv pip install git+https://github.com/grebnetiew/lfs-py.git
```
I also verified that non-LFS repositories still work, with or without
`git-lfs` installed.
### To Replicate
Attempt to use uv to install a Git dependency that contains LFS objects
(e.g. `uv pip install git+https://github.com/grebnetiew/lfs-py.git`).
This should fail with a smudge filter error.
Re-run the same command with the added environment variable
`UV_GIT_LFS=1`. The install should now succeed.
## Potential Changes / Improvements
~With this change LFS objects in a given revision will always be
downloaded if the user has Git LFS installed, which may not always be
desired behavior. It might be helpful to add a field to the `uv`
settings and/or an environment variable so that the LFS step can be
disabled if needed.~
Enabling/disabled via environment variable has now been implemented.
---------
Co-authored-by: Sydney Duckworth <sydduckworth@users.noreply.github.com>
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
Since there are occasional inquiries about how to configure UV for
build-system specific features, I want to raise awareness that users
should refer to the documentation of the build system they are using for
relevant settings.
## Test Plan
Run docs service in local.
9821d58d35
---------
Signed-off-by: FishAlchemist <48265002+FishAlchemist@users.noreply.github.com>
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
You can now run `uv tree --script main.py` to show the dependency tree
for a given script. If a lockfile doesn't exist, it will create one.
Closes https://github.com/astral-sh/uv/issues/7328.
## Summary
You can now run `uv lock --script main.py` to lock a given script
(though as of this PR, the script itself isn't used anywhere).
Closes https://github.com/astral-sh/uv/issues/6318.
* Previously had uv python install, then uv sync --all-extras --dev
* If we are going to use sync for dev dependencies, then the install
step is unneccessary
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
## Test Plan
<!-- How was it tested? -->
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
Add info about uv being available in Scoop.
## Test Plan
`uvx --with-requirements .\docs\requirements.txt mkdocs serve
--config-file mkdocs.public.yml` worked.
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
Follow up to #8553
Clarifies that the `exclude-newer` setting must be a full timestamp and
not a date.
<!-- What's the purpose of the change? What does it do, and why? -->
## Test Plan
N/A
<!-- How was it tested? -->
Zanie Blue
Olly E
Meitar Reihan
Tom Boshoven
John Mumm
Qi Xiao
Charlie Marsh
Nozomi R
ndrew222
johnthagen
Zohar Meir
Aria Desires
Shlomo
Nick Janetakis
Maxime
kenwoodjw
Ahmed Ilyas
InSync
Jatinderjit Singh
Yury Fedotov
Eric Johnson
justin
GCHQDeveloper314
samypr100
Alex Lowe
Victorien
Alex Ball
Mathieu Kniewallner
Song Luar
ChiLin Chiu
konsti
FishAlchemist
Michał Górny
Chao Ning
Lewis
Valentin Oliver Loftsson
Alex Lowe
Tai
samsja
Avasam
Martijn Pieters
Gregory Power
Danilo Rezende
Florian Greinacher
titipoco
Marco Barbosa
Bob Whitelock
Cédric
Ryan
Paul
Jo
3sh V
Niklas Rosenstein
Se7en
Mel Massadian
Eric Mark Martin
Sydney Duckworth
sergue1
Kevin Marchais
csteiner
Olav Rønnestad Birkeland
Trevor Manz
vladislav doster