●Change8

Migrating to uv 0.12.0

Version 0.12.0 introduces 6 breaking changes. This guide details how to update your code.

Released: 7/28/2026

6
Breaking Changes
6
Migration Steps
0
Affected Symbols

Breaking Changes

●Issue #1

Projects created with `uv init` now declare a build system and are packaged by default, using `uv_build`. Existing projects are unaffected. Use `uv init --no-package example` to create the previous unpackaged layout without a build system.

●Issue #2

Unsupported source distribution and wheel archive formats are now rejected. `.tar.bz2` and `.tar.xz` source distributions are no longer accepted. Wheels can no longer contain entries compressed with bzip2, LZMA, or XZ. Rebuild legacy source distributions as `.tar.gz` and regenerate lockfiles.

●Issue #3

Wheel files that could replace the Python interpreter are now rejected. This includes case variants of `python` and interpreter files in `.data/scripts` or `.data/data/bin/python`. Rename conflicting entry points or wheel data files and rebuild the affected wheel.

●Issue #4

The default pre-release handling mode is now `if-necessary`, which prefers stable releases before falling back to pre-releases. This can lead to different version selections than previous uv releases when both stable and pre-release candidates are available. Use `--prerelease disallow`, `--prerelease allow`, or `--prerelease explicit` to control pre-release behavior.

●Issue #5

The `--require-hashes` directive in `requirements.txt` now enforces hash-checking mode. Requirements must be pinned with `==` and include their hash. Remove `--require-hashes` if hash checking is not intended.

●Issue #6

MD5-only hashes are now rejected in hash-checking mode. Hash-checking mode requires at least one secure digest (e.g., SHA-256) for every requirement.

Migration Steps

  1. 1
    If your `[build-system]` table includes an upper bound on `uv_build`, update it to allow `uv_build` 0.12, e.g., `uv_build>=0.11.32,<0.13`.
  2. 2
    If you depend on a legacy source distribution that uses an unsupported format (`.tar.bz2`, `.tar.xz`), rebuild it as a `.tar.gz` archive and regenerate any lockfile containing references to the legacy archive.
  3. 3
    If you encounter issues with wheel files replacing the Python interpreter, rename conflicting entry points or wheel data files and rebuild the affected wheel.
  4. 4
    To control pre-release selection, use `--prerelease disallow` (to disallow pre-releases), `--prerelease allow` (to consider pre-releases without preferring stable first), or `--prerelease explicit` (to only allow pre-releases for direct requirements that mention a pre-release).
  5. 5
    If using `--require-hashes` in `requirements.txt`, ensure every requirement is pinned with `==` and includes its hash. Alternatively, remove `--require-hashes` if hash checking is not intended.
  6. 6
    When using hash-checking mode, ensure that each requirement includes at least one secure hash (e.g., SHA-256) in addition to any MD5 hashes.

Release Summary

This release introduces changes that improve correctness, safety, and compatibility with specifications, with many marked as breaking out of an abundance of caution. Key changes include default packaging for `uv init`, stricter archive format validation, and improved pre-release handling.

Need More Details?

View the full release notes and all changes for uv 0.12.0.

View Full Changelog