Commit Graph

316 Commits

Author SHA1 Message Date
Zanie Blue ede75fe628
Bump version to 0.8.13 (#15423) 2025-08-21 13:52:39 -05:00
Zanie Blue e31f000da7
Add an experimental `uv format` command (#15017)
As a frontend to Ruff's formatter.

There are some interesting choices here, some of which may just be
temporary:

1. We pin a default version of Ruff, so `uv format` is stable for a
given uv version
2. We install Ruff from GitHub instead of PyPI, which means we don't
need a Python interpreter or environment
3. We do not read the Ruff version from the dependency tree

See https://github.com/astral-sh/ruff/pull/19665 for a prototype of the
LSP integration.
2025-08-21 06:33:18 -05:00
Zsolt Dollenstein 5271ce5e24
Fix typo in extra-build-dependencies docs (#15390)
## Summary

Smol but important typo.
2025-08-20 12:39:59 +01:00
Zanie Blue f784c334cf
Bump version to 0.8.12 (#15364) 2025-08-18 22:14:51 +00:00
Charlie Marsh fa3c20a177
Document improvements to build-isolation setups (#15326)
## Summary

There's a lot here (maybe it should go somewhere else?), but this is a
complex topic and I wanted to include a lot of copy-pasteable examples
for common cases.

Closes https://github.com/astral-sh/uv/issues/10694.
Closes https://github.com/astral-sh/uv/issues/13959.
Closes https://github.com/astral-sh/uv/issues/15248.
Closes https://github.com/astral-sh/uv/issues/15316.
2025-08-18 16:15:35 -05:00
Zanie Blue f892276ac8
Bump version to 0.8.11 (#15287) 2025-08-14 14:21:10 -05:00
Zanie Blue 7e817bafde
Bump version to 0.8.10 (#15257) 2025-08-13 20:06:08 +00:00
Zanie Blue 68c0bf8a2c
Bump version to 0.8.9 (#15229) 2025-08-11 21:07:59 -05:00
Zanie Blue 9a54754b0a
Bump version to 0.8.8 (#15184) 2025-08-08 19:03:07 -05:00
Zanie Blue 8a22572338
Bump version to 0.8.7 (#15173) 2025-08-08 14:42:23 -05:00
Zanie Blue 8f71d239f8
Add support for `package`-level conflicts in workspaces (#14906)
Revives https://github.com/astral-sh/uv/pull/9130

Previously, we allowed scoping conflicting extras or groups to specific
packages, e.g. ,`{ package = "foo", extra = "bar" }` for a conflict in
`foo[bar]`. Now, we allow dropping the `extra` or `group` bit and using
`{ package = "foo" }` directly which declares a conflict with `foo`'s
production dependencies.

This means you can declare conflicts between workspace members, e.g.:

```
[tool.uv]
conflicts = [[{ package = "foo" }, { package = "bar" }]]
```

would not allow `foo` and `bar` to be installed at the same time.

Similarly, a conflict can be declared between a package and a group:

```
[tool.uv]
conflicts = [[{ package = "foo" }, { group = "lint" }]]
```

which would mean, e.g., that `--only-group lint` would be required for
the invocation.

As with our existing support for conflicting extras, there are
edge-cases here where the resolver will _not_ fail even if there are
conflicts that render a particular install target unusable. There's test
coverage for some of these. We'll still error at install-time when the
conflicting groups are selected. Due to the likelihood of bugs in this
feature, I've marked it as a preview feature.

I would not recommend reading the commits as there's some slop from not
wanting to rebase Andrew's branch.

---------

Co-authored-by: Andrew Gallant <andrew@astral.sh>
2025-08-08 07:44:58 -05:00
Charlie Marsh 329a6b446a
Bump version to v0.8.6 (#15137) 2025-08-07 16:17:14 +01:00
Zanie Blue ce37286814
Bump version to 0.8.5 (#15093) 2025-08-05 20:21:00 +00:00
Aaron Ang 3df972f18a
Support installing additional executables in `uv tool install` (#14014)
Close #6314

## Summary

Continuing from #7592. Created a new PR to rebase the old branch with
`main`, cleaned up test errors, and improved readability.

## Test Plan

Same test cases as in #7592.

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
2025-07-30 14:50:24 -05:00
Zanie Blue e176e17144
Bump version to 0.8.4 (#14980) 2025-07-30 16:24:20 +00:00
konsti 17f0c91896
Show uv_build in projects documentation (#14968)
Fix https://github.com/astral-sh/uv/issues/14957
2025-07-30 14:04:07 +02:00
Zanie Blue 396e198081
Update documentation for preview flags (#14902)
Follows #14823
2025-07-25 15:19:24 -05:00
Zanie Blue 7e78f54e7c
Bump version to 0.8.3 (#14875) 2025-07-24 15:51:15 -05:00
Zanie Blue 21fadbcc13
Bump version to 0.8.2 (#14832) 2025-07-22 19:39:53 +00:00
Zanie Blue f0151f3a18
Bump version to 0.8.1 (#14818) 2025-07-22 11:36:20 -05:00
Charlie Marsh a3ea1b69f2
Add support for `HF_TOKEN` (#14797)
## Summary

If `HF_TOKEN` is set, we'll automatically wire it up to authenticate
requests when hitting private `huggingface.co` URLs in `uv run`.

## Test Plan

An unauthenticated request:

```
> cargo run -- run https://huggingface.co/datasets/cmarsh/test/resolve/main/main.py

  File "/var/folders/nt/6gf2v7_s3k13zq_t3944rwz40000gn/T/mainYadr5M.py", line 1
    Invalid username or password.
            ^^^^^^^^
SyntaxError: invalid syntax
```

An authenticated request:

```
> HF_TOKEN=hf_... cargo run run https://huggingface.co/datasets/cmarsh/test/resolve/main/main.py

Hello from main.py!
```
2025-07-21 20:55:33 +00:00
Matt Norton d85a300b5f
Fix typo in `concepts/projects/config.md` (#14759) 2025-07-20 17:27:33 -04:00
Zanie Blue 1a339b76e8 Add release notes and bump version for 0.8.0 (#14690)
[Rendered](https://github.com/astral-sh/uv/blob/zb/release-notes/CHANGELOG.md)
2025-07-17 17:20:21 -05:00
Zanie Blue cd40a34522 Build and install workspace members that are dependencies by default (#14663)
Regardless of the presence of a build system, as in
https://github.com/astral-sh/uv/pull/14413

---------

Co-authored-by: John Mumm <jtfmumm@gmail.com>
2025-07-17 17:20:21 -05:00
Zanie Blue 0077f2357f Stabilize addition of Python executables to the bin (#14626)
Closes https://github.com/astral-sh/uv/issues/14296

As mentioned in #14681, this does not stabilize the `--default`
behavior.
2025-07-17 17:20:21 -05:00
John Mumm ff30f14d50 Build `path` sources without build systems by default (#14413)
We currently treat path sources as virtual if they do not specify a
build system, which is surprising behavior. This PR updates the behavior
to treat path sources as packages unless the path source is explicitly
marked as `package = false` or its own `tool.uv.package` is set to
`false`.

Closes #12015

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
2025-07-17 17:20:21 -05:00
Zanie Blue 25e69458b1 Stabilize addition of Python versions to the Windows registry (#14625)
Following #14614 this is non-fatal and has an opt-out so it should be
safe to stabilize.
2025-07-17 17:20:21 -05:00
konsti 3c9aea87b4 `uv init`: Make `uv_build` the default build backend (from `hatchling`) (#14661)
Closes https://github.com/astral-sh/uv/issues/14298

Switch the default build backend for `uv init` from `hatchling` to
`uv_build`.

This change affects the following two commands:

* `uv init --lib`
* `uv init [--app] --package`

It does not affect `uv init` or `uv init --app` without `--package`. `uv
init --build-backend <...>` also works as before.

**Before**

```
$ uv init --lib project
$ cat project/pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
    { name = "konstin", email = "konstin@mailbox.org" }
]
requires-python = ">=3.13.2"
dependencies = []

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```

**After**

```
$ uv init --lib project
$ cat project/pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
    { name = "konstin", email = "konstin@mailbox.org" }
]
requires-python = ">=3.13.2"
dependencies = []

[build-system]
requires = ["uv_build>=0.7.20,<0.8"]
build-backend = "uv_build"
```

I cleaned up some tests for consistency in the second commit.
2025-07-17 17:20:21 -05:00
Zanie Blue 78d6d1134a
Bump version to 0.7.22 (#14685) 2025-07-17 11:27:15 -05:00
Charlie Marsh 7cdc1f62ee
Suggest `uv cache clean` prior to `--reinstall` (#14659)
## Summary

Closes https://github.com/astral-sh/uv/issues/14479.
2025-07-16 12:02:29 -04:00
Zanie Blue 8d6d0678a7
Move "Conflicting dependencies" to the "Resolution" page (#14633) 2025-07-15 16:47:43 -05:00
Zanie Blue ab2bd0179b
Mention the `revision` in the lockfile versioning doc (#14634) 2025-07-15 14:35:54 -05:00
Zanie Blue c226d66f35
Rename "Dependency specifiers" section to exclude PEP 508 reference (#14631) 2025-07-15 12:55:57 -05:00
Charlie Marsh 405ef66cef
Allow users to override index `cache-control` headers (#14620)
## Summary

You can now override the cache control headers for the Simple API, file
downloads, or both:

```toml
[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
cache-control = { api = "max-age=600", files = "max-age=365000000, immutable" }
```

Closes https://github.com/astral-sh/uv/issues/10444.
2025-07-15 10:00:04 -04:00
InSync b046e7f3be
Add missing comma in `projects/dependencies.md` (#14613)
## Summary

Diff:

```diff
 [dependency-groups]
 dev = [
-  {include-group = "lint"}
+  {include-group = "lint"},
   {include-group = "test"}
 ]
```

## Test Plan

None.
2025-07-14 14:06:05 -05:00
Geoffrey Thomas 77c771c7f3
Bump version to 0.7.21 (#14611) 2025-07-14 14:01:28 -04:00
Noam Teyssier 43dbdba578
feature: shorthand for --with (-w) in uvx and uv tool run (#14530)
<!--
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 is a small quality of life feature that adds a shorthand (`-w`) to
the `--with` flag for minimizing keystrokes.

Pretty minor, but I didn't see any conflicts with `-w` and thought this
could be a nice place for it.

```bash
# proposed addition (short)
uvx -w numpy ipython

# original (long)
uvx --with numpy ipython
```

## Test Plan

Added testing already in the P.R. - just copied over tests from the
`--with` flag

<!-- How was it tested? -->
2025-07-10 13:50:50 -05:00
Zanie Blue 573b991398
Add nesting groups documentation for dependency groups (#14539) 2025-07-10 08:10:21 -05:00
konsti e798b09aa4
Multiple modules in namespace packages (#14460)
Support multiple root modules in namespace packages by enumerating them:

```toml
[tool.uv.build-backend]
module-name = ["foo", "bar"]
```

This allows applications with multiple root packages without migrating
to workspaces. Since those are regular module names (we iterate over
them an process each one like a single module names), it allows
combining dotted (namespace) names and regular names. It also
technically allows combining regular and stub modules, even though this
is even less recommends.

We don't recommend this structure (please use a workspace instead, or
structure everything in one root module), but it reduces the number of
cases that need `namespace = true`.

Fixes #14435
Fixes #14438

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
2025-07-09 17:45:44 +00:00
Zanie Blue 812a3e7c34
Bump version to 0.7.20 (#14525) 2025-07-09 12:15:41 -05:00
Zanie Blue 38ee6ec800
Bump version to 0.7.19 (#14431) 2025-07-02 21:19:52 +00:00
konsti 71b5ba13d7
Stabilize the uv build backend (#14311)
The uv build backend has gone through some feedback cycles, we expect no
more major configuration changes, and we're ready to take the next step:
The uv build backend in stable.

This PR stabilizes:

* Using `uv_build` as build backend
* The documentation of the uv build backend
* The direct build fast path, where uv doesn't use PEP 517 if you're
using `uv_build` in a compatible version.
* `uv build --list`, which is limited to `uv_build`.

It does not:
* Make `uv_build` the default on `uv init`
* Make `--package` the default on `uv init`
2025-07-02 15:37:43 -05:00
konsti a7aa46acc5
Add a "choosing a build backend" section to the docs (#14295)
I think the build backend docs as a whole are now ready for review. I
only made a small change here.

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
2025-07-02 09:02:03 -05:00
Zanie Blue 87e9ccfb92
Bump version to 0.7.18 (#14402) 2025-07-01 15:30:44 -05:00
Zanie Blue b1812d111a
Edits to the build backend documentation (#14376)
Co-authored-by: konstin <konstin@mailbox.org>
2025-07-01 08:44:23 +00:00
Charlie Marsh 41c218a89b
Bump version to 0.7.17 (#14347) 2025-06-29 09:58:33 -04:00
Zanie Blue ec18f4813a
Fix typo (#14341) 2025-06-28 11:32:03 -05:00
Zanie Blue b6b7409d13
Bump version to 0.7.16 (#14334) 2025-06-27 16:46:36 -05:00
John Mumm 4ed9c5791b
Bump version to 0.7.15 (#14254) 2025-06-25 12:06:41 +02:00
Aria Desires 92de53f4eb
Bump version to 0.7.14 (#14218) 2025-06-23 12:48:51 -04:00
John Mumm e9d5780369
Support transparent Python patch version upgrades (#13954)
> NOTE: The PRs that were merged into this feature branch have all been
independently reviewed. But it's also useful to see all of the changes
in their final form. I've added comments to significant changes
throughout the PR to aid discussion.

This PR introduces transparent Python version upgrades to uv, allowing
for a smoother experience when upgrading to new patch versions.
Previously, upgrading Python patch versions required manual updates to
each virtual environment. Now, virtual environments can transparently
upgrade to newer patch versions.

Due to significant changes in how uv installs and executes managed
Python executables, this functionality is initially available behind a
`--preview` flag. Once an installation has been made upgradeable through
`--preview`, subsequent operations (like `uv venv -p 3.10` or patch
upgrades) will work without requiring the flag again. This is
accomplished by checking for the existence of a minor version symlink
directory (or junction on Windows).

### Features

* New `uv python upgrade` command to upgrade installed Python versions
to the latest available patch release:
``` 
# Upgrade specific minor version 
uv python upgrade 3.12 --preview
# Upgrade all installed minor versions
uv python upgrade --preview
```
* Transparent upgrades also occur when installing newer patch versions: 
```
uv python install 3.10.8 --preview
# Automatically upgrades existing 3.10 environments
uv python install 3.10.18
```
* Support for transparently upgradeable Python `bin` installations via
`--preview` flag
```
uv python install 3.13 --preview
# Automatically upgrades the `bin` installation if there is a newer patch version available
uv python upgrade 3.13 --preview
```
* Virtual environments can still be tied to a patch version if desired
(ignoring patch upgrades):
```
uv venv -p 3.10.8
```

### Implementation

Transparent upgrades are implemented using:
* Minor version symlink directories (Unix) or junctions (Windows)
* On Windows, trampolines simulate paths with junctions
* Symlink directory naming follows Python build standalone format: e.g.,
`cpython-3.10-macos-aarch64-none`
* Upgrades are scoped to the minor version key (as represented in the
naming format: implementation-minor version+variant-os-arch-libc)
* If the context does not provide a patch version request and the
interpreter is from a managed CPython installation, the `Interpreter`
used by `uv python run` will use the full symlink directory executable
path when available, enabling transparently upgradeable environments
created with the `venv` module (`uv run python -m venv`)

New types:
* `PythonMinorVersionLink`: in a sense, the core type for this PR, this
is a representation of a minor version symlink directory (or junction on
Windows) that points to the highest installed managed CPython patch
version for a minor version key.
* `PythonInstallationMinorVersionKey`: provides a view into a
`PythonInstallationKey` that excludes the patch and prerelease. This is
used for grouping installations by minor version key (e.g., to find the
highest available patch installation for that minor version key) and for
minor version directory naming.

### Compatibility

* Supports virtual environments created with:
  * `uv venv`
* `uv run python -m venv` (using managed Python that was installed or
upgraded with `--preview`)
  * Virtual environments created within these environments
* Existing virtual environments from before these changes continue to
work but aren't transparently upgradeable without being recreated
* Supports both standard Python (`python3.10`) and freethreaded Python
(`python3.10t`)
* Support for transparently upgrades is currently only available for
managed CPython installations

Closes #7287
Closes #7325
Closes #7892
Closes #9031
Closes #12977

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
2025-06-20 16:17:13 +02:00
Jack O'Connor c3e4b63806 document the way member sources shadow workspace sources
Closes https://github.com/astral-sh/uv/issues/14093.
2025-06-18 15:31:23 -07:00
Zanie Blue 62ed17b230
Bump version to 0.7.13 (#14002) 2025-06-12 14:33:31 -05:00
konsti 7316bd01a3
Build backend: Support namespace packages (#13833)
Unlike regular packages, specifying all `__init__.py` directories for a
namespace package would be very verbose There is e.g.
https://github.com/python-poetry/poetry/tree/main/src/poetry, which has
18 modules, or https://github.com/googleapis/api-common-protos which is
inconsistently nested. For both the Google Cloud SDK, there are both
packages with a single module and those with complex structures, with
many having multiple modules due to versioning through `<module>_v1`
versioning. The Azure SDK seems to use one module per package (it's not
explicitly documented but seems to follow from the process in
https://azure.github.io/azure-sdk/python_design.html#azure-sdk-distribution-packages
and
ccb0e03a3d/doc/dev/packaging.md).

For simplicity with complex projects, we add a `namespace = true` switch
which disabled checking for an `__init__.py`. We only check that there's
no `<module_root>/<module_name>/__init__.py` and otherwise add the whole
`<module_root>/<module_name>` folder. This comes at the cost of
`namespace = true` effectively creating an opt-out from our usual checks
that allows creating an almost entirely arbitrary package.

For simple projects with only a single module, the module name can be
dotted to point to the target module, so the build still gets checked:

```toml
[tool.uv.build-backend]
module-name = "poetry.core"
```

## Alternatives

### Declare all packages

We could make `module-name` a list and allow or require declaring all
packages:

```toml
[tool.uv.build-backend]
module-name = ["cloud_sdk.service.storage", "cloud_sdk.service.storage_v1", "cloud_sdk.billing.storage"]
```

Or for Poetry:

```toml
[tool.uv.build-backend]
module-name = [
    "poetry.config",
    "poetry.console",
    "poetry.inspection",
    "poetry.installation",
    "poetry.json",
    "poetry.layouts",
    "poetry.masonry",
    "poetry.mixology",
    "poetry.packages",
    "poetry.plugins",
    "poetry.publishing",
    "poetry.puzzle",
    "poetry.pyproject",
    "poetry.repositories",
    "poetry.toml",
    "poetry.utils",
    "poetry.vcs",
    "poetry.version"
]
```

### Support multiple namespaces

We could also allow namespace packages with multiple root level module:

```toml
[tool.uv.build-backend]
module-name = ["cloud_sdk.my_ext", "local_sdk.my_ext"]
```

For lack of use cases, we delegate this to creating a workspace with one
package per module.

## Implementation

Due to the more complex options for the module name, I'm moving
verification on deserialization later, dropping the source span we'd get
from serde. We also don't show similarly named directories anymore.

---------

Co-authored-by: Andrew Gallant <andrew@astral.sh>
2025-06-12 17:23:58 +00:00
Lan, Jian 90a7208a73
Fix and improve docs (#13620)
<!--
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 follow the advices from the IDE spell checker and grammar checker, fix
some typos, and improve the docs.
2025-06-10 13:15:38 -05:00
Zanie Blue dc3fd46472
Bump version to 0.7.12 (#13892) 2025-06-06 19:42:06 +00:00
Jack O'Connor 94ed6f880f
update Git and GitHub Actions docs to mention `gh auth login` (#13850) 2025-06-05 20:44:59 +00:00
Zanie Blue 262ca73965
Remove the configuration section in favor of concepts / reference (#13842)
Extends https://github.com/astral-sh/uv/pull/13841 — I'll drop that
commit later after that pull request merges but it's small.

I find the split into a "Configuration" section awkward and don't think
it's helping us. Everything moved into the "Concepts" section, except
the "Environment variables" page which definitely belongs in the
reference and the "Installer" page which is fairly niche and seems
better in the reference.

Before / After


<img
src="https://github.com/user-attachments/assets/80d8304b-17da-4900-a5f4-c3ccac96fcc5"
width="400">
2025-06-05 17:09:49 +00:00
Zanie Blue 789a246cf3
Move the pip interface documentation into the concepts section (#13841)
The motivation here being a reduction in the length of the navigation. I
don't think we did this in the first place because we didn't have the
capability to do another nested level, but now we're doing that for
Projects.
2025-06-05 11:53:27 -05:00
Zanie Blue 3ca8d074a4
Use "terminal driver" instead of "shell" in SIGINT docs (#13787)
Addressing the comment at
https://github.com/astral-sh/uv/issues/12108#issuecomment-2925703719
2025-06-03 22:07:03 +00:00
konsti 56203484a2
Add `uv add --bounds` to configure the version constraint (#12946)
By default, uv uses only a lower bound in `uv add`, which avoids
dependency conflicts due to upper bounds. With this PR, this cna be
changed by setting a different bound kind. The bound kind can be
configured in `uv.toml`, as a user preference, in `pyproject.toml`, as a
project preference, or on the CLI, when adding a specific project.

We add two options that add an upper bound on the constraint, one for
SemVer (`>=1.2.3,<2.0.0`, dubbed "major", modeled after the SemVer
caret) and another one for dependencies that make breaking changes in
minor version (`>=1.2.3,<1.3.0`, dubbed "minor", modeled after the
SemVer tilde). Intuitively, the major option bumps the most significant
version component, while the minor option bumps the second most
significant version component. There is also an exact bounds option
(`==1.2.3`), though generally we recommend setting a wider bound and
using the lockfile for pinning.

Versions can have leading zeroes, such as `0.1` or `0.0.1`. For a single
leading 0, we shift the the meaning of major and minor similar to cargo.
For two or more leading zeroes, the difference between major and minor
becomes inapplicable, instead both bump the most significant component:
- major: `0.1` -> `>=0.1,<0.2`
- major: `0.0.1` -> `>=0.0.1,<0.0.2`
- major: `0.0.1.1` -> `>=0.0.1.1,<0.0.2.0`
- major: `0.0.0.1` -> `>=0.0.0.1,<0.0.0.2`
- minor: `0.1` -> `>=0.1,<0.1.1`
- minor: `0.0.1` -> `>=0.0.1,<0.0.2`
- minor: `0.0.1.1` -> `>=0.0.1.1,<0.0.2.0`
- minor: `0.0.0.1` -> `>=0.0.0.1,<0.0.0.2`

For a consistent appearance, we try to preserve the number of components
in the upper bound. For example, adding a version `2.17` with the major
option is stored as `>=2.17,<3.0`. If a version uses three components
and is greater than 0, both bounds will also use three components
(SemVer versions always have three components). Of the top 100 PyPI
packages, 8 use a non-three-component version (docutils, idna, pycparser
and soupsieve with two components, packaging, pytz and tzdata with two
component, CalVer and trove-classifiers with four component CalVer).
Example `pyproject.toml` files with the top 100 packages: [`--bounds
major`](https://gist.github.com/konstin/0aaffa9ea53c4834c22759e8865409f4)
and [`--bounds
minor`](https://gist.github.com/konstin/e77f5e990a7efe8a3c8a97c5c5b76964).
While many projects follow version scheme that roughly or directly
matches the major or minor options, these compatibility ranges are
usually not applicable for the also popular CalVer versioning.

For pre-release versions, there are two framings we could take: One is
that pre-releases generally make no guarantees about compatibility
between them and are used to introduce breaking changes, so we should
pin them exactly. In many cases however, pre-release specifiers are used
because a project needs a bugfix or a feature that hasn't made it into a
stable release, or because a project is compatible with the next version
before a final version for that release is published. In those cases,
compatibility with other packages that depend on the same library is
more important, so the desired bound is the same as it would be for the
stable release, except with the lower bound lowered to include
pre-release.

The names of the bounds and the name of the flag is up for bikeshedding.
Currently, the option is call `tool.uv.bounds`, but we could also move
it under `tool.uv.edit.bounds`, where it would be the first/only entry.

Fixes #6783

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
2025-05-28 13:11:31 +00:00
Jay Qi 2db1630f54
Add documentation about Python versions to Tools concept page (#7673)
<!--
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 documentation about Python versions to Tools concept page

## Test Plan

N/A

---------

Co-authored-by: Jay Qi <jayqi@users.noreply.github.com>
Co-authored-by: Zanie Blue <contact@zanie.dev>
2025-05-27 16:23:29 +00:00
Art O Cathain 1bee9320f1
Clarify adding SSH Git dependencies (#13534)
The current instructions say 

> prefix a Git-compatible URL (i.e., that you would use with git clone)
with git+.

But this does not work with the URL that Github gives you when you
choose Clone -> SSH via the UI, which is of the form
`git@github.com:astral-sh/uv.git`. If you prefix this with `git+`, i.e.

`git+git@github.com:astral-sh/uv.git`

it does not work.

---------

Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
2025-05-20 14:20:15 +00:00
konsti 5386701cc1
Build backend: Make preview default and add configuration docs (#12804)
Add configuration documentation for the build backend and make it the
preview default.

The build backend should generally work with default configuration
unless you want specific features such as flat layout or module
renaming, there is only a dedicated configuration, but no concept or
guide page for the build backend. Once the build backend is stable, we
can update the guide documentation to explain that uv defaults to its
own build backend, but other build backends are also supported.

The uv build backend becomes the default in preview, giving it more
exposure from users and preparing it to make it the default proper. The
current documentation retains warnings that the build backend is in
preview.

To see current uses of `uv_build` on GitHub:
https://github.com/search?q=path%3A**%2Fpyproject.toml+uv_build%3E%3D0&type=code

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
2025-05-05 13:52:31 +00:00
Zanie Blue e2f400adbe
Bump version to 0.6.15 (#13034)
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
2025-04-22 00:03:33 +00:00
Ori Shamir e178cc1b7a
docs: Fix highlight line in explicit index documentation (#12887)
## Summary

Fix the highlighted line in [Index
Documentation](https://docs.astral.sh/uv/concepts/projects/dependencies/#index)
(towards the end of the section) - the `explicit = true` line should be
highlighted.

## Test Plan
Docs.
2025-04-15 15:39:56 -05:00
Henry Schreiner 99ec6ae144
docs: add explicit source (matching PyTorch guide) (#12844)
## Summary

<!-- What's the purpose of the change? What does it do, and why? -->

The PyTorch guide page has this, but it's missing from this example
(which is otherwise identical to the PyTorch guide page). I think it
would be helpful to include it here too.

## Test Plan

Docs.
<!-- How was it tested? -->

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
2025-04-14 08:22:20 -04:00
Charlie Marsh 039b3c5dda
Refine lack of musl distributions to ARM-only (#12825) 2025-04-10 16:35:41 -05:00
Aria Desires 713c0053ef
fix link to issue (#12823)
Also closes #12641
2025-04-10 16:23:33 -04:00
Zanie Blue 29f57a28cf
Fix lockfile note (#12793) 2025-04-10 08:53:02 -05:00
Olly E 335af984f2
Add lockfile note about PEP 751 (#12732)
## 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>
2025-04-07 17:53:36 -05:00
Zanie Blue 1988685029
Add note about `uv build` to `package = false` (#12608)
Closes https://github.com/astral-sh/uv/issues/12352
2025-04-02 08:33:27 -05:00
Qi Xiao 878457b5dd
Update dependencies.md (#12598)
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>
2025-04-01 13:47:27 +00:00
johnthagen 57c57d1011
Fix statement in Required environments docs (#12540)
## Summary

The beginning of the sentence says that the package only publishes
distributions for Linux, so it will only be installable on Linux.
2025-03-28 20:36:59 -04:00
Zanie Blue ec499807f8
Add support for Python version requests in `uv python list` (#12375)
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
```
2025-03-23 03:13:58 +00:00
kenwoodjw cdd6de555b
docs: Update dependencies.md (#12388)
<!--
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? -->
2025-03-22 22:06:11 -05:00
Jatinderjit Singh a95f4cf553
Fix `--directory` path in examples (#12165)
<!--
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>
2025-03-18 15:50:03 -04:00
Aria Desires 26cad18635
add `default-groups = "all"` sugar to `pyproject.toml` (#12289)
Suggested by @zanieb in #10934

* [x] agree we want to do this
* [x] add docs

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
2025-03-18 13:42:06 -05:00
John Mumm f66ce58a09
Simplify managed Python flags (#12246)
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>
2025-03-18 18:13:14 +01:00
Charlie Marsh 7ea2f657fa
Add `src` to default cache keys (#12062)
## 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
2025-03-17 17:56:10 -04:00
Charlie Marsh 72be5ffb25
Always reinstall local source trees passed to `uv pip install` (#12176)
## 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.
2025-03-17 21:12:21 +00:00
Charlie Marsh 3188d99f39
Use consistent commas around i.e. and e.g. (#12157)
## Summary

Only in user-facing docs -- I didn't bother with the rustdoc. (This is
in the style guide already.)
2025-03-13 23:42:10 +00:00
John Mumm 797f1fbac0
Add support for global `uv python pin` (#12115)
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
2025-03-13 13:48:37 +01:00
GCHQDeveloper314 2ac47d76b8
Docs : Quote versions string in python-versions.md (#12112)
<!--
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
2025-03-11 09:03:00 -05:00
samypr100 e096ab2411
Add support for Windows legacy scripts via uv tool run (#12079)
## 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.
2025-03-11 09:02:17 -05:00
Zanie Blue 3739223c96
Fix tool concept page headings (#12053)
Some of these were incorrectly nested, and there was not a heading for
upgrades
2025-03-08 08:49:21 -06:00
Charlie Marsh d4a805544f
Allow users to set `package = true` on `tool.uv.sources` (#12014)
## 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.
2025-03-06 18:28:09 +00:00
Alex Ball 43c8cd8b3f
Docs: Clarify that setting cache-keys overrides defaults (#11895)
## 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>
2025-03-03 02:54:48 +00:00
Zanie Blue 8f0c6f5a6f
Update the "Locking and syncing" page (#11647)
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>
2025-02-26 12:20:27 -06:00
Zanie Blue 1f7f9fdeb4
Add link to environment marker specification (#11748) 2025-02-24 11:57:28 -06:00
Song Luar d4a0096c14
[Docs] fix readme typo (#11742)
<!--
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
2025-02-24 14:24:43 +01:00
Charlie Marsh d8aaa17ccd
Add documentation for required environments (#11542)
## Summary

Right now, there's documentation in the settings reference. This adds
some standalone prose.
2025-02-17 11:27:57 -06:00
Aria Desires fbe9e33b8d
Note that main.py used to be hello.py (#11519)
Co-authored-by: Zanie Blue <contact@zanie.dev>
2025-02-14 21:59:25 +00:00
Aria Desires 9138b35c66 Create `main.py` instead of `hello.py` in `uv init` (#10369)
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
2025-02-13 16:17:49 -06:00
Zanie Blue 03616ebb68
Add note about available versions (#11331)
ref https://github.com/astral-sh/uv/issues/11243#issuecomment-2644104492
2025-02-07 16:10:05 -06:00
Aria Desires 5c4b6d436c
cleanup some dependency-group docs (#11284)
Some additional details, more mentioning of related flags, and some
minor rewordings to avoid misconceptions I had from the current docs.

Closes #11205
2025-02-07 15:40:59 +00:00
samsja 5ce48cf799
add pip install setuptools in flash-attn docs (#11271)
## 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
2025-02-05 20:59:56 -05:00
Zanie Blue 7ec68e1dda
Allow opt-in to `.python-version` in `uv init` with `--pin-python` (#11265)
For use with `--bare`
2025-02-05 17:21:58 -06:00
Zanie Blue 239f3d76b9
Allow the project `VIRTUAL_ENV` warning to be silenced with `--no-active` (#11251)
Follow-up to https://github.com/astral-sh/uv/pull/11189

Closes https://github.com/astral-sh/uv-pre-commit/issues/36
2025-02-05 19:44:46 +00:00
Zanie Blue acbbb2b82a
Add `--bare` option to `uv init` (#11192)
People are looking for a less opinionated version of `uv init`. The goal
here is to create a `pyproject.toml` and nothing else. With the `--lib`
or `--package` flags, we'll still configure a build backend but we won't
create the source tree. This disables things like the default
`description`, author behavior, and VCS.

See

- https://github.com/astral-sh/uv/issues/8178
- https://github.com/astral-sh/uv/issues/7181
- https://github.com/astral-sh/uv/issues/6750
2025-02-05 10:12:27 -06:00