iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
uv 0.12 changes the default for new projects: uv init now creates a packaged application project with a src/ tree and the uv_build backend. Existing projects are not rewritten. Most users can upgrade without changing anything, but stricter artifact and hash validation, prerelease resolution, project discovery, and safer virtual-environment clearing can affect particular workflows. uv 0.12.0 was released on July 28, 2026. Astral’s changelog describes the release; the commands below help identify what to check.
Quick command reference
| Task | Command | What to know |
|---|---|---|
| Create a packaged application | uv init example |
Since 0.12, packaging with uv_build is the default for new application projects. |
| Create an unpackaged project | uv init --no-package example or uv init --bare |
Use either option when you want the earlier unpackaged style. |
| Run a project command | uv run <command> |
uv updates the project environment before running the command. |
| Run a script | uv run script.py |
Project discovery starts from the script’s directory; pass --project to select a project explicitly. |
| Pin a project’s Python request | uv python pin 3.12 |
Writes a .python-version file. A version number is recommended for interoperability with other tools. |
| Install Python | uv python install 3.12 |
uv can download a compatible interpreter; available downloads are bundled with each uv release. |
| Inspect interpreter discovery | uv python find or uv python find --system |
A discovered virtual environment may take precedence by default. --system ignores virtual environments. |
| Clear a virtual environment | uv venv --clear |
A target that is not a virtual environment requires --force. |
| Select a project explicitly | uv run --project path <command> |
The selected path must point to an existing valid project. |
For a normal project, the first project command—such as uv run, uv sync, or uv lock—creates .venv and uv.lock if they do not already exist. See the uv project guide.
What changed in uv 0.12?
New projects are packaged by default
Before 0.12, a default application project did not declare a build system. Now, uv init example generates a project using uv_build, places source code under src/<project_name>/, and adds a [project.scripts] entry. The project is installed into its environment, so its package can be imported and its configured command invoked.
uv init example
cd example
uv run exampleThis default applies to newly initialized projects; it does not rewrite existing ones. To create a project without packaging, use uv init --no-package example or uv init --bare. The project initialization documentation also describes choosing another backend with --build-backend.
#1 Best Overall
Check restrictive build-backend bounds in templates
The changelog says there is no breaking change to uv’s build-backend configuration. The possible snag is a restrictive upper bound in a project template’s [build-system] requirements: a constraint that excludes 0.12 can prevent resolution. Astral gives uv_build>=0.11.32,<0.13 as an example that admits 0.12. Current generated requirements can use a different lower bound, such as uv_build>=0.12.23,<0.13; treat that as a versioned example, not a universal pin to copy.
Artifact and wheel validation is stricter
uv 0.12 rejects unsupported source-distribution formats and compression methods. PEP 625 source distributions use .tar.gz; legacy .tar.bz2 and .tar.xz source distributions are rejected, even if an existing lockfile references them. Legacy .zip source distributions remain supported. For ZIP-based wheels and archives, supported compression methods are stored, DEFLATE, and zstd; bzip2, LZMA, and XZ are rejected. Rebuild affected distributions as .tar.gz and regenerate lockfiles that reference them.
Wheels that could replace the environment’s Python interpreter are also rejected. This includes case-insensitive filename variants such as Python, python.py, or Python.exe, as well as files installed through wheel data paths that could overwrite the interpreter. There is no opt-out: rename and rebuild a conflicting wheel.
Prerelease selection now uses an if-needed fallback
The default prerelease policy is now if-necessary: uv tries stable candidates first and considers prereleases if constraints require them, including constraints discovered through transitive dependencies. If both stable and prerelease versions satisfy the requirements, resolution can select a different version than earlier uv behavior. The older if-necessary-or-explicit spelling remains as a deprecated alias; the changelog also documents disallow, allow, and explicit policies.
Hash-checking directives are enforced
A --require-hashes directive in requirements.txt now enables hash-checking mode for uv pip install and uv pip sync, rather than merely generating a warning and being ignored. In this mode, every requirement must be pinned and hashed. MD5-only hashes are rejected; provide a secure digest such as SHA-256, or remove the directive if hash checking was not intended.
Project discovery and path handling
Scripts determine where discovery starts
When you run uv run path/to/script.py, project and workspace discovery now starts from the script’s directory. That helps when the script belongs to another project, but it may choose a different environment from one discovered from your current working directory. Select the project explicitly when needed:
uv run --project . other-project/script.pyThe path passed to --project must identify an existing, valid project. uv init --project is rejected because that option selects an existing project; use a positional path to initialize a project or --directory to change the working directory.
Relative package-source paths follow –directory
When --directory is used, relative command-line paths for package indexes and find-links are resolved from the selected directory. Absolute paths and indexes from configuration files are unaffected. Also, uv add now preserves absolute paths to local dependencies; those paths can make a project less portable, so prefer relative paths when portability matters.
Python selection: pins, downloads, and discovery
uv can download a compatible Python interpreter automatically. Interpreter choice is contextual: project requires-python, an explicit --python request, version pins, and discovery order all matter. Requests can specify a major, minor, or patch version, a version range, a variant, or an implementation.
.python-versionsupplies a request. uv looks for it in the working directory and parent directories, subject to project and workspace boundaries.- Available managed Python downloads are bundled per uv release, so two uv versions may not offer identical download sets.
- System interpreter search returns the first compatible interpreter it finds; that may not be the newest one.
- Use
uv python find --systemto ignore virtual environments while inspecting system interpreter discovery.
See the Python installation guide and Python version documentation for selection and installation details.
Safety and other compatibility changes to check
Virtual-environment clearing refuses arbitrary directories
uv venv --clear no longer clears a target directory unless uv recognizes it as a virtual environment. Use --force only when clearing a non-venv directory is intentional. Review scripts that previously used --clear on a path without checking its contents.
Free tools Windows power users keep installed
One-click scans. No signup required.
Additional behavior changes
- Broken
.venvsymlinks and virtual-environment metadata errors are now reported instead of being skipped during discovery, which could otherwise lead uv to find and modify an unrelated ancestor environment. uv python install <minor> --reinstallnow reinstalls matching installed patch versions rather than implicitly upgrading to the latest patch. Use--upgradefor the upgrade behavior; combine--upgrade --reinstallto reinstall only the latest patch.uv lock --upgrade-groupnow requires the named dependency group to exist.- PyPy releases available only in unsupported bzip2 archives are no longer available through
uv python install; newer supported releases remain available. uv publishskips distributions with non-normalized filenames instead of warning and attempting to upload them.
What to inspect when upgrading
- Check
uv --versionso you know which 0.12.x behavior you are diagnosing; the changelog includes later patch releases. - If you maintain project templates, inspect the
[build-system]requirement for an upper bound that excludesuv_build0.12. - For package installation or publishing failures, check source-distribution extensions, ZIP compression, wheel contents that resemble interpreter files, requirement pins and hashes, and distribution filename normalization.
- If a script runs in an unexpected environment, check whether script-directory discovery selected a different project; use
--projectto make selection explicit. - Review any automation using
uv venv --clearor reinstalling Python by minor version, since both behaviors now have more specific safeguards or semantics.
The changes above are the 0.12 behavior guide, not a complete inventory of every 0.12.x fix. For patch-specific diagnosis, check the installed version against the current uv changelog.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
