changelogs/0.10.x.md
Since we released uv 0.9.0 in October of 2025, 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 preview features. Python upgrades are now stable,
including the uv python upgrade command, uv python install --upgrade, and automatically
upgrading Python patch versions in virtual environments when a new version is installed. The
add-bounds and extra-build-dependencies settings are now stable. Finally, the uv workspace dir
and uv workspace list utilities for writing scripts against workspace members are now stable.
There are no breaking changes to uv_build. If
you have an upper bound in your [build-system] table, you should update it, e.g., from <0.10.0
to <0.11.0.
Require --clear to remove existing virtual environments in uv venv
(#17757)
Previously, uv venv would prompt for confirmation before removing an existing virtual
environment in interactive contexts, and remove it without confirmation in non-interactive
contexts. Now, uv venv requires the --clear flag to remove an existing virtual environment. A
warning for this change was added in
uv 0.8.
You can opt out of this behavior by passing the --clear flag or setting UV_VENV_CLEAR=1.
Error if multiple indexes include default = true
(#17011)
Previously, uv would silently accept multiple indexes with default = true and use the first one.
Now, uv will error if multiple indexes are marked as the default.
You cannot opt out of this behavior. Remove default = true from all but one index.
Error when an explicit index is unnamed
(#17777)
Explicit indexes can only be used via the [tool.uv.sources] table, which requires referencing
the index by name. Previously, uv would silently accept unnamed explicit indexes, which could
never be referenced. Now, uv will error if an explicit index does not have a name.
You cannot opt out of this behavior. Add a name to the explicit index or remove the entry.
Install alternative Python executables using their implementation name (#17756, #17760)
Previously, uv python install would install PyPy, GraalPy, and Pyodide executables with names
like python3.10 into the bin directory. Now, these executables will be named using their
implementation name, e.g., pypy3.10, graalpy3.10, and pyodide3.12, to avoid conflicting with
CPython installations.
You cannot opt out of this behavior.
Respect global Python version pins in uv tool run and uv tool install
(#14112)
Previously, uv tool run and uv tool install did not respect the global Python version pin (set
via uv python pin --global). Now, these commands will use the global Python version when no
explicit version is requested.
For uv tool install, if the tool is already installed, the Python version will not change unless
--reinstall or --python is provided. If the tool was previously installed with an explicit
--python flag, the global pin will not override it.
You can opt out of this behavior by providing an explicit --python flag.
Remove Debian Bookworm, Alpine 3.21, and Python 3.8 Docker images (#17755)
The Debian Bookworm and Alpine 3.21 images were replaced by Debian Trixie and Alpine 3.22 as defaults in uv 0.9. These older images are now removed. Python 3.8 images are also removed, as Python 3.8 is no longer supported in the Trixie or Alpine base images.
The following image tags are no longer published:
uv:bookworm, uv:bookworm-slimuv:alpine3.21uv:python3.8-*Use uv:debian or uv:trixie instead of uv:bookworm, uv:alpine or uv:alpine3.22 instead of
uv:alpine3.21, and a newer Python version instead of uv:python3.8-*.
Drop PPC64 (big endian) builds (#17626)
uv no longer provides pre-built binaries for PPC64 (big endian). This platform appears to be largely unused and is only supported on a single manylinux version. PPC64LE (little endian) builds are unaffected.
Building uv from source is still supported for this platform.
Skip generating activate.csh for relocatable virtual environments
(#17759)
Previously, uv venv --relocatable would generate an activate.csh script that contained
hardcoded paths, making it incompatible with relocation. Now, the activate.csh script is not
generated for relocatable virtual environments.
You cannot opt out of this behavior.
Require username when multiple credentials match a URL (#16983)
When using uv auth login to store credentials, you can register multiple username and password
combinations for the same host. Previously, when uv needed to authenticate and multiple
credentials matched the URL (e.g., when retrieving a token with uv auth token), uv would pick
the first match. Now, uv will error instead.
You cannot opt out of this behavior. Include the username in the request, e.g.,
uv auth token --username foo example.com.
Avoid invalidating the lockfile versions after an exclude-newer change
(#17721)
Previously, changing the exclude-newer setting would cause package versions to be upgraded,
ignoring the lockfile entirely. Now, uv will only change package versions if they are no longer
within the exclude-newer range.
You can restore the previous behavior by using --upgrade or --upgrade-package to opt-in to
package version changes.
Upgrade uv format to Ruff 0.15.0 (#17838)
uv format now uses Ruff 0.15.0, which
uses the 2026 style guide. See
the blog post for details.
The formatting of code is likely to change. You can opt out of this behavior by requesting an
older Ruff version, e.g., uv format --version 0.14.14.
Update uv crate test features to use test- as a prefix
(#17860)
This change only affects redistributors of uv. The Cargo features used to gate test dependencies,
e.g., pypi, have been renamed with a test- prefix for clarity, e.g., test-pypi.
uv python upgrade and uv python install --upgrade
(#17766)
When installing Python versions, an intermediary directory without the patch version attached will be created, and virtual environments will be transparently upgraded to new patch versions.
See the Python version documentation for more details.
uv add --bounds and the add-bounds configuration option
(#17660)
This does not come with any behavior changes. You will no longer see an experimental warning when
using uv add --bounds or add-bounds in configuration.
uv workspace list and uv workspace dir
(#17768)
This does not come with any behavior changes. You will no longer see an experimental warning when using these commands.
extra-build-dependencies (#17767)
This does not come with any behavior changes. You will no longer see an experimental warning when
using extra-build-dependencies in configuration.
pyx.dev as a target in uv auth commands despite PYX_API_URL differing
(#17856)Released on 2026-02-10.
sdist-vX/.git if it already exists
(#17825)uv python update-shell over uv tool update-shell in Python docs
(#17941)Released on 2026-02-10.
cargo-install failing due to missing uv-test dependency
(#17954)Released on 2026-02-16.
exclude-newer in uv format
(#17651)target-workspace-discovery is enabled
(#17965)uv format
(#17977)cpython-3.1 is specified (#17972)--allow-existing with minor version links on Windows
(#17978)u64::MAX in version segments to prevent overflow
(#17985)Released on 2026-02-17.
uv python errors
(#18008)uv init / --name foo)
(#17983)wheel and sdist files produced by the uv_build build backend
(#18020)Released on 2026-02-23.
uv lock --frozen (#17859)pylock.toml wheels by tags and requires-python
(#18081)uv publish
(#17783)exclude-newer invalidates the lock file
(#18100)--no-emit-workspace with --all-packages on single-member workspaces
(#18098)UV_NO_DEFAULT_GROUPS rejecting truthy values like 1
(#18057)uv export formats (#17900)Released on 2026-02-24.
requires-python conflicting with
.python-version (#18097)Released on 2026-02-27.
Released on 2026-03-03.
--exclude-newer filters out all versions of a package
(#18217)uv_build direct build compatibility
(#17902)UV_INIT_BARE environment variable for uv init
(#18210)uv tool upgrade from installing excluded dependencies
(#18022)pylock.toml files
(#18227)--upgrade (#18226)uv tree orphaned roots and premature deduplication
(#17212)after_script
(#18206)Released on 2026-03-06.
fbgemm-gpu, fbgemm-gpu-genai, torchrec, and torchtune to the PyTorch list
(#18338)uv_build settings without uv_build
(#15750)/usr/lib/os-release on Linux system lookup failure
(#18349)cargo auditable to include SBOM in uv builds
(#18276)UV_VENV_RELOCATABLE
(#18331)cp3-none-any (#17064)Released on 2026-03-13.
--outdated flag to uv tool list (#18318)--project directory does not exist
(#17714)uv init
(#18417)uv cache clear an alias of uv cache clean
(#18420)uv_build
(#18419)uv audit output (#18392)uv audit (#18193)uv audit
(#18394)uv tool install --force
(#18399)uv export
(#18433)Content-Type
(#18334)Released on 2026-03-16.
--project to refer to a pyproject.toml directly and reduce to a warning on other files
(#18513)SYSTEM_VERSION_COMPAT when querying interpreters on macOS
(#18452)uv sync --active recreating active environments when UV_PYTHON_INSTALL_DIR is relative
(#18398)-o requirements.txt in uv pip compile example
(#12308)Released on 2026-03-19.
--no-emit-package
(#18565)uv audit in the CLI help (#18540)uv python list
(#18459)uv-docker-example
(#18558)