Upgrading to uv 0.13.0: The Breaking Changes Worth Checking First

What uv 0.13.0 changes

uv 0.13.0 was released on October 9, 2026. The headline change is that Python 3.15 is now the default stable Python version, replacing 3.14 for any command that needs an interpreter and has not been given one. The release notes add that most users should be able to upgrade without making changes.

Two side effects deserve attention before you run the upgrade. First, uv may download or rebuild dependencies after it, because some cache entries written by earlier versions cannot be reused. That is a one-time cost in time and bandwidth rather than a version conflict, and multiple uv versions can still share a cache directory safely. Second, the release contains several breaking changes to requirements handling, archive extraction and build output. The notes describe them together, which can make the list look more alarming than it is: several already match pip, and the ones that do not come with an opt-out.

Python 3.15 becomes the default

Until this release, the default stable version uv reached for was 3.14. It is now 3.15, which affects Python downloads when no version is requested or pinned, for example when you run uv python install without arguments.

An existing environment is not thrown away. uv continues to use compatible Python installations that are already present, so uv venv can still build on an installed 3.14. The new default only takes effect where uv would otherwise have to fetch something: if no suitable interpreter is installed and automatic downloads are enabled, commands such as uv venv and uvx python can now pull Python 3.15.

Because that decision is about what gets downloaded, not about what your project declares, the fix is to declare it. To stay on 3.14, pass uv venv --python 3.14. For a project, run uv python pin 3.14, which records the version in .python-version so every later command and every teammate sees the same pin. The release itself added CPython 3.15.0 to the list of versions uv can install.

Why the cache reset happens

The cache-format change is filed under performance rather than breaking changes, and that placement is fair but easy to skim past. uv's cache stores downloaded wheels and source distributions so later installs skip the network and, where possible, skip rebuilding. Entries written in an older format cannot be read back, so the first install after the upgrade can behave like a cold cache.

On a laptop this shows up as a slower command. In a continuous integration job with an ephemeral runner and a restored cache directory, it can show up as a longer build and more registry traffic on the first run, then settle. The notes are explicit that the two conditions are separate: you may see downloads, you may see rebuilds, and neither means the upgrade failed. They also confirm that different uv versions can keep sharing one cache directory, so a team mid-migration does not need to split caches.

Requirements handling that now errors

The change most likely to break a pipeline concerns hash checking. uv used to ignore a --require-hashes directive when it appeared inside a constraints file pulled in with -c from a requirements file. It now honours it, which means every requirement in the install must carry hashes. An install that succeeded before can now fail if one requirement is missing a hash.

There is no opt-out while the directive is in the file. The two ways forward are to add the missing hashes or to remove --require-hashes from the included constraints file if hash checking was never intended there.

Editable requirements in included constraints files changed in the other direction. uv used to ignore them silently and now rejects them with an error, matching pip. This one has no opt-out either. Editable requirements belong in a file passed with -r or on the command line with --editable.

Option values also stopped being split on spaces. --constraint, --override, --exclude and --build-constraint now treat each value as a single path, which is what allows a path containing a space to work. The old habit of writing -c "a.txt b.txt" has to become -c a.txt -c b.txt. The equivalent environment variables still accept space-separated lists.

Archives, build output and Windows ARM64

uv now uses tar-codec, replacing astral-tokio-tar, for extracting tar archives, building source distributions with uv_build, and reading their metadata for uv publish. The new backend validates more strictly, so archives containing hard links or unsupported tar extensions that older versions accepted may now be rejected. Source distributions built by uv_build can also come out with different archive bytes, and therefore different hashes, than the same source produced before. Setting UV_LEGACY_TAR_BACKEND=1 restores the previous behaviour.

uv build --clear gained a guard. It used to be able to delete a project or an input source distribution when the output directory happened to contain the source. uv now rejects those output directories, including equivalent paths reached through symlinks, before it clears anything. The fix is to choose an output directory that does not hold build sources, or to drop --clear.

On Windows ARM64, uv now prefers native ARM64 interpreters across Python versions instead of emulated x86_64 ones. The old preference existed because native wheel support was thin, and the release notes point to similar moves in CPython, the official Windows Python install manager and GitHub's actions/setup-python. Where a native interpreter is unavailable, uv still falls back to x86_64 and then to 32-bit x86. You can hold the previous behaviour with UV_PYTHON_ARCH=x86_64 or by requesting an explicit architecture such as cpython-3.14-windows-x86_64.

One smaller change removes work. uv used to write _virtualenv.py and _virtualenv.pth into every new virtual environment to stop distutils configuration from changing install paths. On Python 3.10 and later it no longer does, matching virtualenv 21.6.0, because those versions ignore the affected configuration keys. Existing environments are not modified, so an old one keeps the files and the startup overhead until you recreate it.

Checking the build backend bound

Projects that use uv's own build backend have one line to check. There are no breaking changes to uv_build configuration, but if your [build-system] table puts an upper bound on uv_build, it may now exclude 0.13. The release notes give the shape of the fix: allow uv_build>=0.13.0,<0.14.

The ordering that causes least disruption is to pin your Python version first, then upgrade, then watch the first install for the expected cache rebuild. The two errors worth expecting, a missing hash or an editable requirement inside a constraints file, both name the file that needs the edit.