uv

Breaking changes

What to check before upgrading, taken from the notes of the last 30 releases.

• 0.13.0Oct 9, 2026

  Breaking changes

  • Use Python 3.15 as the default stable version

  The default stable Python version has changed from 3.14 to 3.15. This affects Python downloads when no version is requested or pinned, e.g., when running uv python install.

  uv continues to use compatible Python installations that are already present. For example, uv venv can still use an installed Python 3.14. If no suitable interpreter is installed and automatic downloads are enabled, commands such as uv venv and uvx python can now download Python 3.15.

  You can opt out of this behavior by requesting Python 3.14 explicitly, e.g., uv venv --python 3.14. For projects, use uv python pin 3.14 to record the version in .python-version.

  • Honor --require-hashes in included constraints files (#22275)

  Previously, uv ignored --require-hashes in constraints files included with -c from a requirements file. Now, uv honors the directive and requires hashes for all requirements in the installation. Installs that previously succeeded can now fail if a requirement is missing a hash.

  You cannot opt out while the directive is present. Add the missing hashes to your requirements, or remove the --require-hashes directive from the included constraints file if hash checking is not intended.

  • Prefer native Python on Windows ARM64 (#22100)

  Previously, ARM64 builds of uv preferred emulated x86_64 Python installations because native wheel support was limited. Now, uv prefers native ARM64 (aarch64) interpreters across Python versions.

  This follows similar changes in CPython, the official Windows Python install manager, and GitHub's actions/setup-python.

  When a native interpreter is unavailable, uv continues to fall back to x86_64, then 32-bit x86.

  You can opt out of this behavior by setting UV_PYTHON_ARCH=x86_64 or requesting an explicit architecture, e.g., cpython-3.14-windows-x86_64. If you are using setup-uv, you can set python-arch: x86_64 instead.

  • Reject editable requirements in included constraints files (#22282)

  Previously, uv silently ignored editable (-e) requirements in constraints files included with -c from a requirements file. Now, uv rejects these requirements with an error, matching pip's behavior.

  You cannot opt out of this behavior. Move editable requirements to a requirements file passed with -r, or pass them directly with --editable, instead of including them in a constraints file.

  • Omit the distutils startup patch on Python 3.10 and later (#22096)

  Previously, uv installed _virtualenv.py and _virtualenv.pth into every new virtual environment to prevent distutils configuration from changing installation paths. Now, like virtualenv 21.6.0, uv omits these files on Python 3.10 and later, which already ignore the affected configuration keys. This reduces Python startup overhead. Python 3.9 and earlier retain the patch.

  You cannot opt out of this behavior. Existing virtual environments are not modified automatically. Recreate an environment with Python 3.10 or later to remove the patch.

  This stabilizes the no-distutils-patch preview feature.

  • Treat requirement-file option values as single paths (#22290)

  Previously, uv split values passed to --constraint, --override, --exclude, and --build-constraint on spaces, even when quoted. Now, each value is treated as a single path, allowing file paths containing spaces.

  You cannot opt out of this behavior. Repeat the option to provide multiple files. For example, replace -c "a.txt b.txt" with -c a.txt -c b.txt.

  Space-separated lists in UV_CONSTRAINT, UV_OVERRIDE, UV_EXCLUDE, and UV_BUILD_CONSTRAINT remain supported.