Since we released uv 0.7.0 in April, we've accumulated various changes that improve correctness and user experience, but could break some workflows. This release contains those changes; many have been marked as breaking out of an abundance of caution. We expect most users to be able to upgrade without making changes.
This release also includes the stabilization of a couple uv python install features, which have been available under preview since late last year.
Breaking changes
Install Python executables into a directory on the PATH (#14626)
uv python install now installs a versioned Python executable (e.g., python3.13) into a directory on the PATH (e.g., ~/.local/bin) by default. This behavior has been available under the --preview flag since Oct 2024. This change should not be breaking unless it shadows a Python executable elsewhere on the PATH.
To install unversioned executables, i.e., python3 and python, use the --default flag. The --default flag has also been in preview, but is not stabilized in this release.
Note that these executables point to the base Python installation and only include the standard library. That means they will not include dependencies from your current project (use uv run python instead) and you cannot install packages into their environment (use uvx --with <package> python instead).
As with tool installation, the target directory respects common variables like XDG_BIN_HOME and can be overridden with a UV_PYTHON_BIN_DIR variable.
You can opt out of this behavior with uv python install --no-bin or UV_PYTHON_INSTALL_BIN=0.
Register Python versions with the Windows Registry (#14625)
uv python install now registers the installed Python version with the Windows Registry as specified by PEP 514. This allows using uv installed Python versions via the py launcher. This behavior has been available under the --preview flag since Jan 2025. This change should not be breaking, as using the uv Python versions with py requires explicit opt in.
You can opt out of this behavior with uv python install --no-registry or UV_PYTHON_INSTALL_REGISTRY=0.
Prompt before removing an existing directory in uv venv (#14309)
Previously, uv venv would remove an existing virtual environment without confirmation. While this is consistent with the behavior of project commands (e.g., uv sync), it's surprising to users that are using imperative workflows (i.e., uv pip). Now, uv venv will prompt for confirmation before removing an existing virtual environment. If not in an interactive context, uv will still remove the virtual environment for backwards compatibility. However, this behavior is likely to change in a future release.
The behavior for other commands (e.g., uv sync) is unchanged.
You can opt out of this behavior by setting UV_VENV_CLEAR=1 or passing the --clear flag.
Validate that discovered interpreters meet the Python preference (#7934)
uv allows opting out of its managed Python versions with the --no-managed-python and python-preference options.
Previously, uv would not enforce this option for Python interpreters discovered on the PATH. For example, if a symlink to a managed Python interpreter was created, uv would allow it to be used even if --no-managed-python was provided. Now, uv ignores Python interpreters that do not match the Python preference unless they are in an active virtual environment or are explicitly requested, e.g., with --python /path/to/python3.13.
Similarly, uv would previously not invalidate existing project environments if they did not match the Python preference. Now, uv will invalidate and recreate project environments when the Python preference changes.
You can opt out of this behavior by providing the explicit path to the Python interpreter providing --managed-python / --no-managed-python matching the interpreter you want.
Install dependencies without build systems when they are path sources (#14413)
When working on a project, uv uses the presence of a build system to determine if it should be built and installed into the environment. However, when a project is a dependency of another project, it can be surprising for the dependency to be missing from the environment.
Previously, uv would not build and install dependencies with path sources unless they declared a build system or set tool.uv.package = true. Now, dependencies with path sources are built and installed regardless of the presence of a build system. If a build system is not present, the setuptools.build_meta:__legacy__ backend will be used (per PEP 517).
You can opt out of this behavior by setting package = false in the source declaration, e.g.:
[tool.uv.sources]foo={path="./foo",package=false}
Or, by setting tool.uv.package = false in the dependent pyproject.toml.
Install dependencies without build systems when they are workspace members (#14663)
As described above for dependencies with path sources, uv previously would not build and install workspace members that did not declare a build system. Now, uv will build and install workspace members that are a dependency of another workspace member regardless of the presence of a build system. The behavior is unchanged for workspace members that are not included in the project.dependencies, project.optional-dependencies, or dependency-groups tables of another workspace member.
You can opt out of this behavior by setting tool.uv.package = false in the workspace member's pyproject.toml.
Bump --python-platform linux to manylinux_2_28 (#14300)
uv allows performing platform-specific resolution for explicit targets and provides short aliases, e.g., linux, for common targets.
Previously, the default target for --python-platform linux was manylinux_2_17, which is compatible with most Linux distributions from 2014 or newer. We now default to manylinux_2_28, which is compatible with most Linux distributions from 2019 or newer. This change follows the lead of other tools, such as cibuildwheel, which changed their default to manylinux_2_28 in Mar 2025.
This change only affects users requesting a specific target platform. Otherwise, uv detects the manylinux target from your local glibc version.
You can opt out of this behavior by using --python-platform x86_64-manylinux_2_17 instead.
In Apr 2025, uv changed the uv version command to an interface for viewing and updating the version of the current project. However, when outside a project, uv version would continue to display uv's version for backwards compatibility. Now, when used outside of a project, uv version will fail.
You cannot opt out of this behavior. Use uv self version instead.
Require --global for removal of the global Python pin (#14169)
Previously, uv python pin --rm would allow you to remove the global Python pin without opt in. Now, uv requires the --global flag to remove the global Python pin.
You cannot opt out of this behavior. Use the --global flag instead.
Support conflicting editable settings across groups (#14197)
Previously, uv would always treat a package as editable if any requirement requested it as editable. However, this prevented users from declaring path sources that toggled the editable setting across dependency groups. Now, uv allows declaring different editable values for conflicting groups. However, if a project includes a path dependency twice, once with editable = true and once without any editable annotation, those are now considered conflicting, and uv will exit with an error.
Make uv_build the default build backend in uv init (#14661)
The uv build backend (uv_build) was stabilized in uv 0.7.19. Now, it is the default build backend for uv init --package and uv init --lib. Previously, hatchling was the default build backend. A build backend is still not used without opt-in in uv init, but we expect to change this in a future release.
You can opt out of this behavior with uv init --build-backend hatchling.
Set default UV_TOOL_BIN_DIR on Docker images (#13391)
Previously, UV_TOOL_BIN_DIR was not set in Docker images which meant that uv tool install did not install tools into a directory on the PATH without additional configuration. Now, UV_TOOL_BIN_DIR is set to /usr/local/bin in all Docker derived images.
When the default image user is overridden (e.g. USER <UID>) with a less privileged user, this may cause uv tool install to fail.
You can opt out of this behavior by setting an alternative UV_TOOL_BIN_DIR.
Update --check to return an exit code of 1 (#14167)
uv uses an exit code of 1 to indicate a "successful failure" and an exit code of 2 to indicate an "error".
Previously, uv lock --check and uv sync --check would exit with a code of 2 when the lockfile or environment were outdated. Now, uv will exit with a code of 1.
You cannot opt out of this behavior.
Use an ephemeral environment for uv run --with invocations (#14447)
When using uv run --with, uv layers the requirements requested using --with into another virtual environment and caches it. Previously, uv would invoke the Python interpreter in this layered environment. However, this allows poisoning the cached environment and introduces race conditions for concurrent invocations. Now, uv will layer another empty virtual environment on top of the cached environment and invoke the Python interpreter there. This should only cause breakage in cases where the environment is being inspected at runtime.
You cannot opt out of this behavior.
Restructure the uv venv command output and exit codes (#14546)
Previously, uv used miette to format the uv venv output. However, this was inconsistent with most of the uv CLI. Now, the output is a little different and the exit code has switched from 1 to 2 for some error cases.
You cannot opt out of this behavior.
Default to --workspace when adding subdirectories (#14529)
When using uv add to add a subdirectory in a workspace, uv now defaults to adding the target as a workspace member.
You can opt out of this behavior by providing --no-workspace.
Add missing validations for disallowed uv.toml fields (#14322)
uv does not allow some settings in the uv.toml. Previously, some settings were silently ignored when present in the uv.toml. Now, uv will error.
You cannot opt out of this behavior. Use --no-config or remove the invalid settings.
Configuration
Add support for toggling Python bin and registry install options via env vars (#14662)
This PR contains the following updates:
| Package | Type | Update | Change |
|---|---|---|---|
| [ghcr.io/astral-sh/uv](https://github.com/astral-sh/uv) | final | minor | `0.7.20` -> `0.8.0` |
---
### Release Notes
<details>
<summary>astral-sh/uv (ghcr.io/astral-sh/uv)</summary>
### [`v0.8.0`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#080)
[Compare Source](https://github.com/astral-sh/uv/compare/0.7.22...0.8.0)
Since we released uv [0.7.0](https://github.com/astral-sh/uv/releases/tag/0.7.0) in April, we've accumulated various changes that improve correctness and user experience, but could break some workflows. This release contains those changes; many have been marked as breaking out of an abundance of caution. We expect most users to be able to upgrade without making changes.
This release also includes the stabilization of a couple `uv python install` features, which have been available under preview since late last year.
##### Breaking changes
- **Install Python executables into a directory on the `PATH` ([#​14626](https://github.com/astral-sh/uv/pull/14626))**
`uv python install` now installs a versioned Python executable (e.g., `python3.13`) into a directory on the `PATH` (e.g., `~/.local/bin`) by default. This behavior has been available under the `--preview` flag since [Oct 2024](https://github.com/astral-sh/uv/pull/8458). This change should not be breaking unless it shadows a Python executable elsewhere on the `PATH`.
To install unversioned executables, i.e., `python3` and `python`, use the `--default` flag. The `--default` flag has also been in preview, but is not stabilized in this release.
Note that these executables point to the base Python installation and only include the standard library. That means they will not include dependencies from your current project (use `uv run python` instead) and you cannot install packages into their environment (use `uvx --with <package> python` instead).
As with tool installation, the target directory respects common variables like `XDG_BIN_HOME` and can be overridden with a `UV_PYTHON_BIN_DIR` variable.
You can opt out of this behavior with `uv python install --no-bin` or `UV_PYTHON_INSTALL_BIN=0`.
See the [documentation on installing Python executables](https://docs.astral.sh/uv/concepts/python-versions/#installing-python-executables) for more details.
- **Register Python versions with the Windows Registry ([#​14625](https://github.com/astral-sh/uv/pull/14625))**
`uv python install` now registers the installed Python version with the Windows Registry as specified by [PEP 514](https://peps.python.org/pep-0514/). This allows using uv installed Python versions via the `py` launcher. This behavior has been available under the `--preview` flag since [Jan 2025](https://github.com/astral-sh/uv/pull/10634). This change should not be breaking, as using the uv Python versions with `py` requires explicit opt in.
You can opt out of this behavior with `uv python install --no-registry` or `UV_PYTHON_INSTALL_REGISTRY=0`.
- **Prompt before removing an existing directory in `uv venv` ([#​14309](https://github.com/astral-sh/uv/pull/14309))**
Previously, `uv venv` would remove an existing virtual environment without confirmation. While this is consistent with the behavior of project commands (e.g., `uv sync`), it's surprising to users that are using imperative workflows (i.e., `uv pip`). Now, `uv venv` will prompt for confirmation before removing an existing virtual environment. **If not in an interactive context, uv will still remove the virtual environment for backwards compatibility. However, this behavior is likely to change in a future release.**
The behavior for other commands (e.g., `uv sync`) is unchanged.
You can opt out of this behavior by setting `UV_VENV_CLEAR=1` or passing the `--clear` flag.
- **Validate that discovered interpreters meet the Python preference ([#​7934](https://github.com/astral-sh/uv/pull/7934))**
uv allows opting out of its managed Python versions with the `--no-managed-python` and `python-preference` options.
Previously, uv would not enforce this option for Python interpreters discovered on the `PATH`. For example, if a symlink to a managed Python interpreter was created, uv would allow it to be used even if `--no-managed-python` was provided. Now, uv ignores Python interpreters that do not match the Python preference *unless* they are in an active virtual environment or are explicitly requested, e.g., with `--python /path/to/python3.13`.
Similarly, uv would previously not invalidate existing project environments if they did not match the Python preference. Now, uv will invalidate and recreate project environments when the Python preference changes.
You can opt out of this behavior by providing the explicit path to the Python interpreter providing `--managed-python` / `--no-managed-python` matching the interpreter you want.
- **Install dependencies without build systems when they are `path` sources ([#​14413](https://github.com/astral-sh/uv/pull/14413))**
When working on a project, uv uses the [presence of a build system](https://docs.astral.sh/uv/concepts/projects/config/#build-systems) to determine if it should be built and installed into the environment. However, when a project is a dependency of another project, it can be surprising for the dependency to be missing from the environment.
Previously, uv would not build and install dependencies with [`path` sources](https://docs.astral.sh/uv/concepts/projects/dependencies/#path) unless they declared a build system or set `tool.uv.package = true`. Now, dependencies with `path` sources are built and installed regardless of the presence of a build system. If a build system is not present, the ` setuptools.build_meta:__legacy__ ` backend will be used (per [PEP 517](https://peps.python.org/pep-0517/#source-trees)).
You can opt out of this behavior by setting `package = false` in the source declaration, e.g.:
```toml
[tool.uv.sources]
foo = { path = "./foo", package = false }
```
Or, by setting `tool.uv.package = false` in the dependent `pyproject.toml`.
See the documentation on [virtual dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#virtual-dependencies) for details.
- **Install dependencies without build systems when they are workspace members ([#​14663](https://github.com/astral-sh/uv/pull/14663))**
As described above for dependencies with `path` sources, uv previously would not build and install workspace members that did not declare a build system. Now, uv will build and install workspace members that are a dependency of *another* workspace member regardless of the presence of a build system. The behavior is unchanged for workspace members that are not included in the `project.dependencies`, `project.optional-dependencies`, or `dependency-groups` tables of another workspace member.
You can opt out of this behavior by setting `tool.uv.package = false` in the workspace member's `pyproject.toml`.
See the documentation on [virtual dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#virtual-dependencies) for details.
- **Bump `--python-platform linux` to `manylinux_2_28` ([#​14300](https://github.com/astral-sh/uv/pull/14300))**
uv allows performing [platform-specific resolution](https://docs.astral.sh/uv/concepts/resolution/#platform-specific-resolution) for explicit targets and provides short aliases, e.g., `linux`, for common targets.
Previously, the default target for `--python-platform linux` was `manylinux_2_17`, which is compatible with most Linux distributions from 2014 or newer. We now default to `manylinux_2_28`, which is compatible with most Linux distributions from 2019 or newer. This change follows the lead of other tools, such as `cibuildwheel`, which changed their default to `manylinux_2_28` in [Mar 2025](https://github.com/pypa/cibuildwheel/pull/2330).
This change only affects users requesting a specific target platform. Otherwise, uv detects the `manylinux` target from your local glibc version.
You can opt out of this behavior by using `--python-platform x86_64-manylinux_2_17` instead.
- **Remove `uv version` fallback ([#​14161](https://github.com/astral-sh/uv/pull/14161))**
In [Apr 2025](https://github.com/astral-sh/uv/pull/12349), uv changed the `uv version` command to an interface for viewing and updating the version of the current project. However, when outside a project, `uv version` would continue to display uv's version for backwards compatibility. Now, when used outside of a project, `uv version` will fail.
You cannot opt out of this behavior. Use `uv self version` instead.
- **Require `--global` for removal of the global Python pin ([#​14169](https://github.com/astral-sh/uv/pull/14169))**
Previously, `uv python pin --rm` would allow you to remove the global Python pin without opt in. Now, uv requires the `--global` flag to remove the global Python pin.
You cannot opt out of this behavior. Use the `--global` flag instead.
- **Support conflicting editable settings across groups ([#​14197](https://github.com/astral-sh/uv/pull/14197))**
Previously, uv would always treat a package as editable if any requirement requested it as editable. However, this prevented users from declaring `path` sources that toggled the `editable` setting across dependency groups. Now, uv allows declaring different `editable` values for conflicting groups. However, if a project includes a path dependency twice, once with `editable = true` and once without any editable annotation, those are now considered conflicting, and uv will exit with an error.
You cannot opt out of this behavior. Use consistent `editable` settings or [mark groups as conflicting](https://docs.astral.sh/uv/concepts/projects/config/#conflicting-dependencies).
- **Make `uv_build` the default build backend in `uv init` ([#​14661](https://github.com/astral-sh/uv/pull/14661))**
The uv build backend (`uv_build`) was [stabilized in uv 0.7.19](https://github.com/astral-sh/uv/releases/tag/0.7.19). Now, it is the default build backend for `uv init --package` and `uv init --lib`. Previously, `hatchling` was the default build backend. A build backend is still not used without opt-in in `uv init`, but we expect to change this in a future release.
You can opt out of this behavior with `uv init --build-backend hatchling`.
- **Set default `UV_TOOL_BIN_DIR` on Docker images ([#​13391](https://github.com/astral-sh/uv/pull/13391))**
Previously, `UV_TOOL_BIN_DIR` was not set in Docker images which meant that `uv tool install` did not install tools into a directory on the `PATH` without additional configuration. Now, `UV_TOOL_BIN_DIR` is set to `/usr/local/bin` in all Docker derived images.
When the default image user is overridden (e.g. `USER <UID>`) with a less privileged user, this may cause `uv tool install` to fail.
You can opt out of this behavior by setting an alternative `UV_TOOL_BIN_DIR`.
- **Update `--check` to return an exit code of 1 ([#​14167](https://github.com/astral-sh/uv/pull/14167))**
uv uses an exit code of 1 to indicate a "successful failure" and an exit code of 2 to indicate an "error".
Previously, `uv lock --check` and `uv sync --check` would exit with a code of 2 when the lockfile or environment were outdated. Now, uv will exit with a code of 1.
You cannot opt out of this behavior.
- **Use an ephemeral environment for `uv run --with` invocations ([#​14447](https://github.com/astral-sh/uv/pull/14447))**
When using `uv run --with`, uv layers the requirements requested using `--with` into another virtual environment and caches it. Previously, uv would invoke the Python interpreter in this layered environment. However, this allows poisoning the cached environment and introduces race conditions for concurrent invocations. Now, uv will layer *another* empty virtual environment on top of the cached environment and invoke the Python interpreter there. This should only cause breakage in cases where the environment is being inspected at runtime.
You cannot opt out of this behavior.
- **Restructure the `uv venv` command output and exit codes ([#​14546](https://github.com/astral-sh/uv/pull/14546))**
Previously, uv used `miette` to format the `uv venv` output. However, this was inconsistent with most of the uv CLI. Now, the output is a little different and the exit code has switched from 1 to 2 for some error cases.
You cannot opt out of this behavior.
- **Default to `--workspace` when adding subdirectories ([#​14529](https://github.com/astral-sh/uv/pull/14529))**
When using `uv add` to add a subdirectory in a workspace, uv now defaults to adding the target as a workspace member.
You can opt out of this behavior by providing `--no-workspace`.
- **Add missing validations for disallowed `uv.toml` fields ([#​14322](https://github.com/astral-sh/uv/pull/14322))**
uv does not allow some settings in the `uv.toml`. Previously, some settings were silently ignored when present in the `uv.toml`. Now, uv will error.
You cannot opt out of this behavior. Use `--no-config` or remove the invalid settings.
##### Configuration
- Add support for toggling Python bin and registry install options via env vars ([#​14662](https://github.com/astral-sh/uv/pull/14662))
### [`v0.7.22`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0722)
[Compare Source](https://github.com/astral-sh/uv/compare/0.7.21...0.7.22)
##### Python
- Upgrade GraalPy to 24.2.2
See the [GraalPy release notes](https://github.com/oracle/graalpython/releases/tag/graal-24.2.2) for more details.
##### Configuration
- Add `UV_COMPILE_BYTECODE_TIMEOUT` environment variable ([#​14369](https://github.com/astral-sh/uv/pull/14369))
- Allow users to override index `cache-control` headers ([#​14620](https://github.com/astral-sh/uv/pull/14620))
- Add `UV_LIBC` to override libc selection in multi-libc environment ([#​14646](https://github.com/astral-sh/uv/pull/14646))
##### Bug fixes
- Fix `--all-arches` when paired with `--only-downloads` ([#​14629](https://github.com/astral-sh/uv/pull/14629))
- Skip Windows Python interpreters that return a broken MSIX package code ([#​14636](https://github.com/astral-sh/uv/pull/14636))
- Warn on invalid `uv.toml` when provided via direct path ([#​14653](https://github.com/astral-sh/uv/pull/14653))
- Improve async signal safety in Windows exception handler ([#​14619](https://github.com/astral-sh/uv/pull/14619))
##### Documentation
- Mention the `revision` in the lockfile versioning doc ([#​14634](https://github.com/astral-sh/uv/pull/14634))
- Move "Conflicting dependencies" to the "Resolution" page ([#​14633](https://github.com/astral-sh/uv/pull/14633))
- Rename "Dependency specifiers" section to exclude PEP 508 reference ([#​14631](https://github.com/astral-sh/uv/pull/14631))
- Suggest `uv cache clean` prior to `--reinstall` ([#​14659](https://github.com/astral-sh/uv/pull/14659))
##### Preview features
- Make preview Python registration on Windows non-fatal ([#​14614](https://github.com/astral-sh/uv/pull/14614))
- Update preview installation of Python executables to be non-fatal ([#​14612](https://github.com/astral-sh/uv/pull/14612))
- Add `uv python update-shell` ([#​14627](https://github.com/astral-sh/uv/pull/14627))
### [`v0.7.21`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0721)
[Compare Source](https://github.com/astral-sh/uv/compare/0.7.20...0.7.21)
##### Python
- Restore the SQLite `fts4`, `fts5`, `rtree`, and `geopoly` extensions on macOS and Linux
See the
[`python-build-standalone` release notes](https://github.com/astral-sh/python-build-standalone/releases/tag/20250712)
for more details.
##### Enhancements
- Add `--python-platform` to `uv sync` ([#​14320](https://github.com/astral-sh/uv/pull/14320))
- Support pre-releases in `uv version --bump` ([#​13578](https://github.com/astral-sh/uv/pull/13578))
- Add `-w` shorthand for `--with` ([#​14530](https://github.com/astral-sh/uv/pull/14530))
- Add an exception handler on Windows to display information on crash ([#​14582](https://github.com/astral-sh/uv/pull/14582))
- Add hint when Python downloads are disabled ([#​14522](https://github.com/astral-sh/uv/pull/14522))
- Add `UV_HTTP_RETRIES` to customize retry counts ([#​14544](https://github.com/astral-sh/uv/pull/14544))
- Follow leaf symlinks matched by globs in `cache-key` ([#​13438](https://github.com/astral-sh/uv/pull/13438))
- Support parent path components (`..`) in globs in `cache-key` ([#​13469](https://github.com/astral-sh/uv/pull/13469))
- Improve `cache-key` performance ([#​13469](https://github.com/astral-sh/uv/pull/13469))
##### Preview features
- Add `uv sync --output-format json` ([#​13689](https://github.com/astral-sh/uv/pull/13689))
##### Bug fixes
- Do not re-resolve with a new Python version in `uv tool` if it is incompatible with `--python` ([#​14606](https://github.com/astral-sh/uv/pull/14606))
##### Documentation
- Document how to nest dependency groups with `include-group` ([#​14539](https://github.com/astral-sh/uv/pull/14539))
- Fix repeated word in Pyodide doc ([#​14554](https://github.com/astral-sh/uv/pull/14554))
- Update CONTRIBUTING.md with instructions to format Markdown files via Docker ([#​14246](https://github.com/astral-sh/uv/pull/14246))
- Fix version number for `setup-python` ([#​14533](https://github.com/astral-sh/uv/pull/14533))
</details>
---
### Configuration
📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).
🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.
♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 **Ignore**: Close this PR and you won't be reminded about this update again.
---
- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box
---
This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzOS4yNjQuMCIsInVwZGF0ZWRJblZlciI6IjM5LjI2NC4wIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
This PR contains the following updates:
0.7.20->0.8.0Release Notes
astral-sh/uv (ghcr.io/astral-sh/uv)
v0.8.0Compare Source
Since we released uv 0.7.0 in April, we've accumulated various changes that improve correctness and user experience, but could break some workflows. This release contains those changes; many have been marked as breaking out of an abundance of caution. We expect most users to be able to upgrade without making changes.
This release also includes the stabilization of a couple
uv python installfeatures, which have been available under preview since late last year.Breaking changes
Install Python executables into a directory on the
PATH(#14626)uv python installnow installs a versioned Python executable (e.g.,python3.13) into a directory on thePATH(e.g.,~/.local/bin) by default. This behavior has been available under the--previewflag since Oct 2024. This change should not be breaking unless it shadows a Python executable elsewhere on thePATH.To install unversioned executables, i.e.,
python3andpython, use the--defaultflag. The--defaultflag has also been in preview, but is not stabilized in this release.Note that these executables point to the base Python installation and only include the standard library. That means they will not include dependencies from your current project (use
uv run pythoninstead) and you cannot install packages into their environment (useuvx --with <package> pythoninstead).As with tool installation, the target directory respects common variables like
XDG_BIN_HOMEand can be overridden with aUV_PYTHON_BIN_DIRvariable.You can opt out of this behavior with
uv python install --no-binorUV_PYTHON_INSTALL_BIN=0.See the documentation on installing Python executables for more details.
Register Python versions with the Windows Registry (#14625)
uv python installnow registers the installed Python version with the Windows Registry as specified by PEP 514. This allows using uv installed Python versions via thepylauncher. This behavior has been available under the--previewflag since Jan 2025. This change should not be breaking, as using the uv Python versions withpyrequires explicit opt in.You can opt out of this behavior with
uv python install --no-registryorUV_PYTHON_INSTALL_REGISTRY=0.Prompt before removing an existing directory in
uv venv(#14309)Previously,
uv venvwould remove an existing virtual environment without confirmation. While this is consistent with the behavior of project commands (e.g.,uv sync), it's surprising to users that are using imperative workflows (i.e.,uv pip). Now,uv venvwill prompt for confirmation before removing an existing virtual environment. If not in an interactive context, uv will still remove the virtual environment for backwards compatibility. However, this behavior is likely to change in a future release.The behavior for other commands (e.g.,
uv sync) is unchanged.You can opt out of this behavior by setting
UV_VENV_CLEAR=1or passing the--clearflag.Validate that discovered interpreters meet the Python preference (#7934)
uv allows opting out of its managed Python versions with the
--no-managed-pythonandpython-preferenceoptions.Previously, uv would not enforce this option for Python interpreters discovered on the
PATH. For example, if a symlink to a managed Python interpreter was created, uv would allow it to be used even if--no-managed-pythonwas provided. Now, uv ignores Python interpreters that do not match the Python preference unless they are in an active virtual environment or are explicitly requested, e.g., with--python /path/to/python3.13.Similarly, uv would previously not invalidate existing project environments if they did not match the Python preference. Now, uv will invalidate and recreate project environments when the Python preference changes.
You can opt out of this behavior by providing the explicit path to the Python interpreter providing
--managed-python/--no-managed-pythonmatching the interpreter you want.Install dependencies without build systems when they are
pathsources (#14413)When working on a project, uv uses the presence of a build system to determine if it should be built and installed into the environment. However, when a project is a dependency of another project, it can be surprising for the dependency to be missing from the environment.
Previously, uv would not build and install dependencies with
pathsources unless they declared a build system or settool.uv.package = true. Now, dependencies withpathsources are built and installed regardless of the presence of a build system. If a build system is not present, thesetuptools.build_meta:__legacy__backend will be used (per PEP 517).You can opt out of this behavior by setting
package = falsein the source declaration, e.g.:Or, by setting
tool.uv.package = falsein the dependentpyproject.toml.See the documentation on virtual dependencies for details.
Install dependencies without build systems when they are workspace members (#14663)
As described above for dependencies with
pathsources, uv previously would not build and install workspace members that did not declare a build system. Now, uv will build and install workspace members that are a dependency of another workspace member regardless of the presence of a build system. The behavior is unchanged for workspace members that are not included in theproject.dependencies,project.optional-dependencies, ordependency-groupstables of another workspace member.You can opt out of this behavior by setting
tool.uv.package = falsein the workspace member'spyproject.toml.See the documentation on virtual dependencies for details.
Bump
--python-platform linuxtomanylinux_2_28(#14300)uv allows performing platform-specific resolution for explicit targets and provides short aliases, e.g.,
linux, for common targets.Previously, the default target for
--python-platform linuxwasmanylinux_2_17, which is compatible with most Linux distributions from 2014 or newer. We now default tomanylinux_2_28, which is compatible with most Linux distributions from 2019 or newer. This change follows the lead of other tools, such ascibuildwheel, which changed their default tomanylinux_2_28in Mar 2025.This change only affects users requesting a specific target platform. Otherwise, uv detects the
manylinuxtarget from your local glibc version.You can opt out of this behavior by using
--python-platform x86_64-manylinux_2_17instead.Remove
uv versionfallback (#14161)In Apr 2025, uv changed the
uv versioncommand to an interface for viewing and updating the version of the current project. However, when outside a project,uv versionwould continue to display uv's version for backwards compatibility. Now, when used outside of a project,uv versionwill fail.You cannot opt out of this behavior. Use
uv self versioninstead.Require
--globalfor removal of the global Python pin (#14169)Previously,
uv python pin --rmwould allow you to remove the global Python pin without opt in. Now, uv requires the--globalflag to remove the global Python pin.You cannot opt out of this behavior. Use the
--globalflag instead.Support conflicting editable settings across groups (#14197)
Previously, uv would always treat a package as editable if any requirement requested it as editable. However, this prevented users from declaring
pathsources that toggled theeditablesetting across dependency groups. Now, uv allows declaring differenteditablevalues for conflicting groups. However, if a project includes a path dependency twice, once witheditable = trueand once without any editable annotation, those are now considered conflicting, and uv will exit with an error.You cannot opt out of this behavior. Use consistent
editablesettings or mark groups as conflicting.Make
uv_buildthe default build backend inuv init(#14661)The uv build backend (
uv_build) was stabilized in uv 0.7.19. Now, it is the default build backend foruv init --packageanduv init --lib. Previously,hatchlingwas the default build backend. A build backend is still not used without opt-in inuv init, but we expect to change this in a future release.You can opt out of this behavior with
uv init --build-backend hatchling.Set default
UV_TOOL_BIN_DIRon Docker images (#13391)Previously,
UV_TOOL_BIN_DIRwas not set in Docker images which meant thatuv tool installdid not install tools into a directory on thePATHwithout additional configuration. Now,UV_TOOL_BIN_DIRis set to/usr/local/binin all Docker derived images.When the default image user is overridden (e.g.
USER <UID>) with a less privileged user, this may causeuv tool installto fail.You can opt out of this behavior by setting an alternative
UV_TOOL_BIN_DIR.Update
--checkto return an exit code of 1 (#14167)uv uses an exit code of 1 to indicate a "successful failure" and an exit code of 2 to indicate an "error".
Previously,
uv lock --checkanduv sync --checkwould exit with a code of 2 when the lockfile or environment were outdated. Now, uv will exit with a code of 1.You cannot opt out of this behavior.
Use an ephemeral environment for
uv run --withinvocations (#14447)When using
uv run --with, uv layers the requirements requested using--withinto another virtual environment and caches it. Previously, uv would invoke the Python interpreter in this layered environment. However, this allows poisoning the cached environment and introduces race conditions for concurrent invocations. Now, uv will layer another empty virtual environment on top of the cached environment and invoke the Python interpreter there. This should only cause breakage in cases where the environment is being inspected at runtime.You cannot opt out of this behavior.
Restructure the
uv venvcommand output and exit codes (#14546)Previously, uv used
mietteto format theuv venvoutput. However, this was inconsistent with most of the uv CLI. Now, the output is a little different and the exit code has switched from 1 to 2 for some error cases.You cannot opt out of this behavior.
Default to
--workspacewhen adding subdirectories (#14529)When using
uv addto add a subdirectory in a workspace, uv now defaults to adding the target as a workspace member.You can opt out of this behavior by providing
--no-workspace.Add missing validations for disallowed
uv.tomlfields (#14322)uv does not allow some settings in the
uv.toml. Previously, some settings were silently ignored when present in theuv.toml. Now, uv will error.You cannot opt out of this behavior. Use
--no-configor remove the invalid settings.Configuration
v0.7.22Compare Source
Python
See the GraalPy release notes for more details.
Configuration
UV_COMPILE_BYTECODE_TIMEOUTenvironment variable (#14369)cache-controlheaders (#14620)UV_LIBCto override libc selection in multi-libc environment (#14646)Bug fixes
--all-archeswhen paired with--only-downloads(#14629)uv.tomlwhen provided via direct path (#14653)Documentation
revisionin the lockfile versioning doc (#14634)uv cache cleanprior to--reinstall(#14659)Preview features
uv python update-shell(#14627)v0.7.21Compare Source
Python
fts4,fts5,rtree, andgeopolyextensions on macOS and LinuxSee the
python-build-standalonerelease notesfor more details.
Enhancements
--python-platformtouv sync(#14320)uv version --bump(#13578)-wshorthand for--with(#14530)UV_HTTP_RETRIESto customize retry counts (#14544)cache-key(#13438)..) in globs incache-key(#13469)cache-keyperformance (#13469)Preview features
uv sync --output-format json(#13689)Bug fixes
uv toolif it is incompatible with--python(#14606)Documentation
include-group(#14539)setup-python(#14533)Configuration
📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
This PR has been generated by Renovate Bot.