Release Notes

Released on 2026-07-28.

Since we released uv 0.11.0 in March, we've accumulated changes that improve correctness, safety, and compatibility with specifications, 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.

There are no breaking changes to the configuration of the uv build backend. 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.

Breaking changes

• Define build systems by default with uv init (#19197)

  Projects created with uv init now declare a build system and are packaged by default. This was the default project layout all the way back in v0.3, but we found that the use of the hatchling build system was confusing to newcomers and consequently dropped use of a build system by default in v0.4. Since then, we've created our own build system (uv_build) with tight integration with uv and are excited to restore the default to a best-practice project layout.

  Previously, uv init example created an unpackaged layout containing main.py and a pyproject.toml without a build system. The project could declare dependencies but was not itself installed into its virtual environment.

  Now, uv init example defines a [build-system] using uv_build, places application source code in src/example, and includes a [project.scripts] entry named example. Defining a build system allows the project to be imported from tests or other code, installed as a dependency, and run as a command:

  $ uv init example
  $ cd example
  $ uv run example
  Hello from example!

  Existing projects are unaffected. Use uv init --no-package example to create the previous unpackaged layout without a build system.

  See the project creation documentation for more details.

  This stabilizes the packaged-init preview feature.

• Reject unsupported source distribution and wheel archive formats (#18927)

  PEP 625 requires source distributions to use .tar.gz archives. Previously, uv also accepted legacy formats such as .tar.bz2 and .tar.xz. Those formats are now rejected, including when referenced by an existing lockfile. Legacy .zip source distributions remain supported for backwards compatibility.

  Wheels and other ZIP archives can no longer contain entries compressed with bzip2, LZMA, or XZ. Entries must use the stored, DEFLATE, or zstd compression methods.

  Removing support for uncommon compression methods reduces uv's compression dependencies and the attack surface exposed when processing untrusted packages.

  You cannot opt out of this behavior. If you depend on a legacy source distribution that uses an unsupported format, we recommend rebuilding it as a .tar.gz archive and regenerating any lockfile containing references to the legacy archive.

• Reject wheel files that could replace the Python interpreter (#20748, #20749)

  uv already rejected wheel entry points named python, but case variants such as Python were still accepted. On case-insensitive filesystems, including common macOS and Windows setups, these entry points could overwrite the virtual environment's interpreter.

  Wheels could also place interpreter files in their .data/scripts directory or in paths such as .data/data/bin/python, bypassing the entry-point check and replacing the interpreter during installation.

  uv now rejects case-insensitive variants of reserved interpreter names and wheel data files that would be installed over an interpreter. This includes names such as Python, python.py, and Python.exe, along with other reserved interpreter names and their versioned variants.

  You cannot opt out of these checks. Rename conflicting entry points or wheel data files and rebuild the affected wheel.

• Prefer stable releases before falling back to pre-releases (#19993)

  A dependency can introduce a pre-release requirement after resolution starts. uv previously required each package's pre-release eligibility to be known before resolution began: the default if-necessary-or-explicit mode allowed them for direct requirements that explicitly requested a pre-release, or for packages that only published pre-releases.

  This meant that a pre-release requirement discovered in a dependency's metadata, e.g., example>=2.0.0b1, would fail to resolve even when a compatible pre-release existed. To resolve it, you had to add that dependency as a direct requirement or allow pre-releases across your entire dependency graph.

  The default mode is now if-necessary. uv tries stable candidates first and falls back to pre-releases when no stable candidate satisfies the active constraints. Like pip, uv now supports pre-release requirements discovered transitively, but can select different versions than previous uv releases when both stable and pre-release candidates are available.

  You can opt out of automatic pre-release selection with --prerelease disallow. Alternatively, --prerelease allow considers pre-releases without first preferring stable releases, and --prerelease explicit only allows them for direct requirements that mention a pre-release.

  The old if-necessary-or-explicit mode distinguished between explicitly requested pre-releases and packages with no stable releases. That distinction is unnecessary now that if-necessary handles both cases, including transitive requirements. The old name remains available as an alias but is deprecated and will be removed in a future release.

• Respect --require-hashes directives in requirements.txt (#19336)

  Previously, uv pip install and uv pip sync warned about --require-hashes inside a requirements.txt file but still installed dependencies without checking their hashes. Now, the directive enables hash-checking mode, just as if --require-hashes had been passed on the command line.

  For example, this requirements file is no longer accepted because the requirement is neither pinned nor hashed:

  --require-hashes
  anyio
  

  You cannot opt out while the directive is present. Pin every requirement with == and provide its hash, or remove --require-hashes if hash checking is not intended.

• Reject MD5-only hashes in hash-checking mode (#20758)

  Previously, uv pip install --require-hashes and uv pip sync --require-hashes accepted requirements whose only available digest used MD5. MD5 is not collision-resistant, so relying on it undermined installations that require hash verification and differed from pip's behavior.

  Hash-checking mode now requires at least one secure digest for every requirement. For example, the following requirement is rejected unless a secure hash, such as SHA-256, is also supplied:

  anyio==4.0.0 --hash=md5:420d85e19168705cdf0223621b18831a
  

  A secure hash can be supplied directly on the requirement or in a matching constraints file. Ordinary hash verification without --require-hashes continues to support MD5.

  You cannot opt out while hash checking is required. Regenerate affected hashes with SHA-256 or another supported secure hash.

• Reject invalid pylock.toml files and artifacts (#20402, #20440, #20443)

  uv now validates additional requirements from the pylock.toml specification:

  • The packages array must be present. Previously, uv interpreted a missing array as an empty lockfile, so uv pip sync could uninstall an environment instead of rejecting malformed input. An explicitly empty packages = [] array remains valid.
  • Lockfile filenames must be pylock.toml or a single-name variant such as pylock.dev.toml. Names such as pylock..toml and pylock.foo.bar.toml are rejected.
  • If a wheel, source distribution, or other artifact declares a size, the downloaded or cached artifact must match. Previously, an incorrect size was accepted when the hash was correct. Sizes reported by package indexes remain advisory.

  You cannot opt out of these checks. Regenerate malformed lockfiles, rename invalid filenames, and either correct or remove an incorrect optional size value.

• Honor explicit certificate overrides even when no certificates can be loaded (#20741, #20767)

  Previously, uv ignored SSL_CERT_FILE or SSL_CERT_DIR values that pointed to missing or inaccessible paths, empty files or directories, or sources without valid certificates. Instead, it fell back to its default trust roots, potentially allowing HTTPS connect...

Release Notes

Released on 2026-07-28.

Enhancements

• Abort panics in release builds for smaller uv binaries (#20271)
• Use .tar.gz archives for Pyodide installs (#20667)

Preview features

• Avoid checking any scripts in uv check unless --script is passed (#20676)
• Check locked tools for malware before cache reuse (#20301)
• Write and read package.metadata-free lockfiles (#20688, #20691, #20685, #20695)

Bug fixes

• Correctly split dependencies into production and optional markers (#20671)
• Fix discrepancies in argument parsing of exclude-newer (#20679)
• Cleanup managed Python temporary directory on error (#20752)

Install uv 0.11.33

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.11.33/uv-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://releases.astral.sh/github/uv/releases/download/0.11.33/uv-installer.ps1 | iex"

Download uv 0.11.33

Verifying GitHub Artifact Attestations

The artifacts in this release have attestations generated with GitHub Artifact Attestations. These can be verified by using the GitHub CLI:

gh attestation verify <file-path of downloaded artifact> --repo astral-sh/uv

You can also download the attestation from GitHub and verify against that directly:

gh attestation verify <file-path of downloaded artifact> --bundle <file-path of downloaded attestation>

Release Notes

Released on 2026-07-23.

Preview features

• Add --package and --all-packages selection to uv check (#20628)
• Allow uv upgrade to update multiple marker-specific declarations of the same package (#20335)
• Reject non-canonically formatted lockfiles in uv lock --check and commands using --locked (#20646)
• Regenerate non-canonically formatted lockfiles with uv lock --refresh (#20634)
• Include best-effort information about the active environment in uv workspace metadata by default (#20643)

Performance

• Skip dependency-group conflict expansion when no additional conflicts can be inferred (#20611)

Bug fixes

• Fork universal resolutions when Requires-Python is discovered only from distribution metadata (#20586)

Install uv 0.11.32

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.11.32/uv-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://releases.astral.sh/github/uv/releases/download/0.11.32/uv-installer.ps1 | iex"

Download uv 0.11.32

Verifying GitHub Artifact Attestations

The artifacts in this release have attestations generated with GitHub Artifact Attestations. These can be verified by using the GitHub CLI:

gh attestation verify <file-path of downloaded artifact> --repo astral-sh/uv

You can also download the attestation from GitHub and verify against that directly:

gh attestation verify <file-path of downloaded artifact> --bundle <file-path of downloaded attestation>

Release Notes

Released on 2026-07-21.

Enhancements

• Allow workspace sources to reference members in another workspace by path (#18401)
• Support .venv files containing paths to centralized project environments (#20022)
• Update bundled Windows timezone data to IANA 2026c (#20554)

Preview features

• Add an index-specific hash-algorithm setting for lockfile generation (#20605)

Configuration

• Add audit.malware-check and audit.malware-check-url settings (#20587)

Performance

• Avoid quadratic work when deduplicating transitive conflicts (#20578)

Bug fixes

• Suggest --emit-build-options for unsupported uv pip compile --emit-options (#20582)
• Reject source distributions and wheels with mismatched package names (#20432)
• Avoid retrying TLS certificate verification failures (#16245)
• Avoid warnings about uv_build settings for in-tree build backends (#20153)

Install uv 0.11.31

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.11.31/uv-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://releases.astral.sh/github/uv/releases/download/0.11.31/uv-installer.ps1 | iex"

Download uv 0.11.31

Verifying GitHub Artifact Attestations

The artifacts in this release have attestations generated with GitHub Artifact Attestations. These can be verified by using the GitHub CLI:

gh attestation verify <file-path of downloaded artifact> --repo astral-sh/uv

You can also download the attestation from GitHub and verify against that directly:

gh attestation verify <file-path of downloaded artifact> --bundle <file-path of downloaded attestation>

Release Notes

Released on 2026-07-20.

Python

• Add CPython 3.15.0b4 (#20519)

Preview features

• Allow uv workspace metadata --sync to target the active virtual environment with --active (#20500)
• Reuse centralized project environments when workspaces are accessed through symlinks (#20436)

Performance

• Skip resolver candidates whose files are all excluded by exclude-newer (#20460)
• Limit parallel cache reads to reduce resolver scheduling and allocation overhead (#20427)
• Accelerate lockfile serialization with toml_writer (#20450)
• Compact cached Simple API distribution metadata and hashes (#20463, #20483)
• Decode stale cache entries in a single blocking task (#20486)
• Decode cached payloads outside resolver workers (#20464)
• Cache resolver Python requirement markers (#20461)
• Reuse resolver fork markers while recording preferences (#20462)

Bug fixes

• Prevent skipped tar-wheel entries from causing unrelated files to be removed during uninstall (#20429)
• Preserve literal extends-environment paths in pyvenv.cfg on Unix (#20466)

Documentation

• Add a contribution guide (#20511, #20552)

Install uv 0.11.30

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.11.30/uv-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://releases.astral.sh/github/uv/releases/download/0.11.30/uv-installer.ps1 | iex"

Download uv 0.11.30

Verifying GitHub Artifact Attestations

The artifacts in this release have attestations generated with GitHub Artifact Attestations. These can be verified by using the GitHub CLI:

gh attestation verify <file-path of downloaded artifact> --repo astral-sh/uv

You can also download the attestation from GitHub and verify against that directly:

gh attestation verify <file-path of downloaded artifact> --bundle <file-path of downloaded attestation>

Release Notes

Released on 2026-07-15.

Python

• Use gzip-compressed artifacts for PyPy downloads (#20265)

Enhancements

• Add JSON output to uv tree (#19978)
• Add CUDA 13.2 as a supported PyTorch backend (#20267)
• Prefer local artifacts over URLs when installing from pylock.toml (#20393)
• Clarify diagnostics for unsatisfiable direct requirement ranges (#20227)
• Include the selected project name in missing-extra errors (#20358)

Preview features

• Preserve extras and dependency-group conflict context when selecting locked project tools (#20078)
• Split OSV audit queries that exceed the service's 1,000-package limit (#20398)
• Apply OSV fixed-version information only to the matching package and ecosystem (#20399)
• Skip the virtualenv distutils monkeypatch on Python 3.10 and later (#20222)
• Report invalid uv audit --service-url values instead of panicking (#20374)
• Include preview settings in the published SchemaStore schema (#20304)

Performance

• Reduce resolver work by widening selected versions across ranges without other known candidates (#20115)
• Defer client and build setup for no-op uv sync operations (#20364)
• Reuse workspace discovery during frozen syncs (#20363)
• Reuse workspace discovery after resolving settings (#20356)
• Reuse workspace discovery in uv tree, uv export, uv format, and uv audit (#20359)
• Avoid cache and interpreter setup when reading a project version (#20360)

Bug fixes

• Reject duplicate active package entries in pylock.toml (#20391)
• Preserve direct-archive hashes in uv pip freeze output (#20395)
• Explain conflicting root requirements instead of displaying an empty version range (#20228)
• Prevent build-backend data paths from escaping the project or bypassing wheel exclusions (#20397)
• Reject PEP 517 backend paths outside the source tree, including paths that escape through symlinks (#20387)
• Redact credentials from failed Git fetch commands (#20401)
• Fix exclusive post-release range ordering to match PEP 440 (#20268)
• Canonicalize equivalent PEP 440 ranges during dependency resolution (#20182)
• Honor Python version pins when initializing scripts (#20404)
• Respect package-scoped source filtering for scripts (#20389)
• Report existing environment incompatibilities when uv pip install --strict has nothing to install (#20388)
• Continue scanning platlib when purelib is missing (#20405)
• Handle versionless .egg-info files as legacy package metadata (#20403)
• Make repeated locking idempotent for impossible cross-variable platform markers (#20369)
• Report invalid cloud credential endpoint URLs instead of panicking (#20372)
• Report invalid pylock.toml artifact URLs instead of panicking (#20373)
• Report non-UTF-8 virtual environment paths instead of panicking while generating activation scripts (#20375)
• Return an unsupported-operation error from unimplemented build-backend requirement hooks (#20376)

Documentation

• Clarify --no-build behavior for editable requirements (#20234)
• Document uv's threat model (#20236)
• Reduce the number of badges in the README (#11257)

Install uv 0.11.29

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.11.29/uv-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://releases.astral.sh/github/uv/releases/download/0.11.29/uv-installer.ps1 | iex"

Download uv 0.11.29

Release Notes

Released on 2026-07-07.

Security

This release updates our ZIP library, astral-async-zip, to v0.0.20, which includes 15 changes that harden our ZIP handling against parser differentials. uv may reject ZIP archives with malformed or ambiguous content that were previously accepted.

See the upstream commits for a full list of changes.

Python

• Upgrade GraalPy to 25.1.3 (#20069)

Enhancements

• Improve trace logs for unexpected error chains (#20220)
• Move lockfile update guidance to a hint (#20219)
• Preserve indentation for multiline error causes (#20156)
• Render user errors with their cause chains (#20217)
• Route final command errors through the printer to respect -q and -qq (#20163)
• Use standard rendering for uv build errors (#20159)
• Use standard rendering for tool requirement errors (#20160)

Performance

• Only compile bytecode for installed distributions in uv pip install (#19914)
• Avoid allocating URL-safe Git revisions (#20194)
• Avoid allocating canonical Python request strings (#20193)
• Avoid allocating custom Astral mirror URLs (#20204)
• Avoid allocating expanded compatibility tags (#20190)
• Avoid allocating shell strings that need no escaping (#20196)
• Avoid allocating static ABI descriptions (#20201)
• Avoid allocating static Windows executable names (#20200)
• Avoid allocating static dependency table names (#20199)
• Avoid allocating static platform triple components (#20195)
• Avoid allocating static resolver report labels (#20198)
• Avoid allocating static unavailable-version messages (#20197)
• Avoid allocating unchanged Python download architectures (#20202)
• Avoid allocating unchanged paths during case normalization (#20203)
• Avoid allocations when expanding group conflicts (#20211)
• Avoid allocations when formatting requirements (#20206)
• Avoid cloning credential lookup services (#20210)
• Avoid cloning dry-run distributions (#20209)
• Avoid cloning owned dependency metadata (#20212)
• Avoid redundant direct URL clones (#20207)
• Create metadata version errors lazily (#20205)
• Optimize expanded tag compatibility checks (#20171)
• Optimize parsing of single-digit three-part versions (#20118)

Bug fixes

• Avoid overflow when computing HTTP cache age (#20178)
• Respect --upgrade when upgrade-package is configured (#19955)
• Support uv tree in dependency-group-only projects (#20167)
• Treat cache entries as stale at exact expiration (#20183)

Install uv 0.11.28

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.11.28/uv-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://releases.astral.sh/github/uv/releases/download/0.11.28/uv-installer.ps1 | iex"

Download uv 0.11.28

Verifying GitHub Artifact Attestations

The artifacts in this release have attestations generated with GitHub Artifact Attestations. These can be verified by using the GitHub CLI:

gh attestation verify <file-...

Release Notes

Released on 2026-07-06.

Enhancements

• Continue on ignored errors when fetching wheel metadata (#12255)
• Use caching for --python-downloads-json-url (#16749)

Preview features

• Discover extensionless shebang scripts in uv workspace list --scripts (#20099)

Performance

• Avoid full site-packages scans for direct reinstalls (#20119)
• Avoid redundant pyproject parsing (#20076)
• Cache default dependency markers when reading locks (#20125)
• Enable SIMD-accelerated TOML parsing (#20079)
• Intern requires-python specifiers in Simple API parsing (#20104)
• Read cache entries into exact-sized buffers (#20120)
• Reduce VersionSpecifiers parsing allocations (#20105)
• Reduce site-packages scan allocation overhead (#20087)
• Reuse package names when parsing wheel filenames (#20110)
• Sort Simple API files after grouping (#20112)

Bug fixes

• Always emit packages table for pylock.toml (#20145)
• Avoid blank line for empty uv pip tree (#20062)
• Encode hashes in file paths (#19807)
• Error on a registry uv.lock package without a version instead of panicking (#19855)
• Preserve conditional extra markers in exports (#20148)
• Skip the ambiguous authority check for file transport VCS URLs (#20086)
• Sync index format when uv add --index updates an existing index URL (#19818)

Other changes

• Re-add pub APIs used in Pixi (#20074)
• Update Rust toolchain to 1.96.1 (#20103)

Install uv 0.11.27

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.11.27/uv-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://releases.astral.sh/github/uv/releases/download/0.11.27/uv-installer.ps1 | iex"

Download uv 0.11.27

Verifying GitHub Artifact Attestations

The artifacts in this release have attestations generated with GitHub Artifact Attestations. These can be verified by using the GitHub CLI:

gh attestation verify <file-path of downloaded artifact> --repo astral-sh/uv

You can also download the attestation from GitHub and verify against that directly:

gh attestation verify <file-path of downloaded artifact> --bundle <file-path of downloaded attestation>

Release Notes

Released on 2026-06-30.

Performance

• Adapt uv to IDs-only PubGrub dependencies (#20048)
• Avoid allocations in ForkMap::contains (#20023)
• Reuse resolver work across PubGrub iterations (#20020)
• Speed up candidate selection for disjoint ranges (#20026)

Bug fixes

• Warn when the build cache is inside the source directory (#20056)

Install uv 0.11.26

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.11.26/uv-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://releases.astral.sh/github/uv/releases/download/0.11.26/uv-installer.ps1 | iex"

Download uv 0.11.26

Verifying GitHub Artifact Attestations

The artifacts in this release have attestations generated with GitHub Artifact Attestations. These can be verified by using the GitHub CLI:

gh attestation verify <file-path of downloaded artifact> --repo astral-sh/uv

You can also download the attestation from GitHub and verify against that directly:

gh attestation verify <file-path of downloaded artifact> --bundle <file-path of downloaded attestation>

Release Notes

Released on 2026-06-26.

Security

This release updates our tar library, astral-tokio-tar, to v0.6.3, which includes over 20 changes that harden our tar handling against parser differentials. uv may reject source distributions with malformed or ambiguous content that were previously accepted.

See the upstream commits for a full list of changes.

Enhancements

• Add a full "lockfile" to tool receipts (#18937)
• Allow scoped overrides to add dependencies (#19974)
• Avoid writing redundant lockfile markers with tool.uv.environments (#19933)
• Factor supported environments out of lockfile markers (#19969)
• Recommend our own build backend in the build frontend (#19994)
• Reject wheels with multiple .dist-info directories (#19986)
• Simplify dependency markers under parent reachability (#19971)
• Support scoped dependency exclusions (#19977)
• Support scoped dependency overrides (#19970)
• Explain why files are skipped in registry index parsing (#19983)

Preview features

• Add uv workspace list --scripts (#20009)
• Support centralised environments in uv venv (#19912)
• Use locked ty versions in uv check (#19884)
• Add centralized storage of project environments (#18214)
• Verify lockfile hashes before reusing a cached ty in uv check (#19995)
• Use locked dependency selection for uv check --script (#19989)

Bug fixes

• Preserve standalone markers in workspace metadata (#20011)
• Reject uv build if the cache dir is enclosed (#19991)

Install uv 0.11.25

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.11.25/uv-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://releases.astral.sh/github/uv/releases/download/0.11.25/uv-installer.ps1 | iex"

Download uv 0.11.25

Verifying GitHub Artifact Attestations

The artifacts in this release have attestations generated with GitHub Artifact Attestations. These can be verified by using the GitHub CLI:

gh attestation verify <file-path of downloaded artifact> --repo astral-sh/uv

You can also download the attestation from GitHub and verify against that directly:

gh attestation verify <file-path of downloaded artifact> --bundle <file-path of downloaded attestation>