changelogs/0.6.x.md
There have been 31 releases and 1135 pull requests since 0.5.0, our last release with breaking changes. As before, we've accumulated various changes that improve correctness and user experience, 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.
Create main.py instead of hello.py in uv init
(#10369)
Previously, uv init created a hello.py sample file. Now, uv init will create main.py
instead — which aligns with expectations from user feedback. The --bare option can be used to
avoid creating the file altogether.
Respect UV_PYTHON in uv python install
(#11487)
Previously, uv python install did not read this environment variable; now it does. We believe
this matches user expectations, however, this will take priority over .python-version files
which could be considered breaking.
Set UV to the uv executable path (#11326)
When uv spawns a subprocess, it will now have the UV environment variable set to the uv binary
path. This change is breaking if you are setting the UV environment variable yourself, as we
will overwrite its value.
Additionally, this change requires marking the uv Rust entrypoint (uv::main) as unsafe to
avoid unsoundness — this is only relevant if you are invoking uv using Rust. See the
Rust documentation for details about
the safety of updating a process' environment.
Error on non-existent extras, e.g., in uv sync
(#11426)
Previously, uv would silently ignore non-existent extras requested on the command-line (e.g., via
uv sync --extra foo). This is generally correct behavior when resolving requests for package
extras, because an extra may be present on one compatible version of a package but not another.
However, this flexibility doesn't need to apply to the local project and it's less surprising to
error here.
Error on missing dependency groups when --frozen is provided
(#11499)
Previously, uv would not validate that the requested dependency groups were present in the
lockfile when the --frozen flag was used. Now, an error will be raised if a requested dependency
group is not present.
Change -p to a --python alias in uv pip compile
(#11486)
In uv pip compile, -p was an alias for --python-version while everywhere else in uv's
interface it is an alias for --python. Additionally, uv pip compile did not respect the
UV_PYTHON environment variable. Now, the semantics of this flag have been updated for parity
with the rest of the CLI.
However, --python-version is unique: if we cannot find an interpreter with the given version, we
will not fail. Instead, we'll use an alternative interpreter and override its version tags with
the requested version during package resolution. This behavior is retained here for backwards
compatibility, --python <version> / -p <version> will not fail if the version cannot be found.
However, if a specific interpreter is requested, e.g., with --python <path> or --python pypy,
and cannot be found — uv will exit with an error.
The breaking changes here are that UV_PYTHON is respected and --python <version> will no
longer fail if the version cannot be found.
Bump alpine default tag to 3.21 for derived Docker images
(#11157)
Alpine 3.21 was released in Dec 2024 and is used in the official Alpine-based Python images. Our
uv:python3.x-alpine images have been using 3.21 since uv v0.5.8. However, now the uv:alpine
image will use 3.21 instead of 3.20 and uv:alpine3.20 will no longer be updated.
Use files instead of junctions on Windows (#11269)
Previously, we used junctions for atomic replacement of cache entries on Windows. Now, we use a file with a pointer to the cache entry instead. This resolves various edge-case behaviors with junctions. These files are only intended to be consumed by uv and the cache version has been bumped. We do not think this change will affect workflows.
uv publish is no longer in preview (#11032)
This does not come with any behavior changes. You will no longer see an experimental warning when
using uv publish. See the linked pull request for a report on the stabilization.
--active for PEP 723 script environments
(#11433)revision to the lockfile to allow backwards-compatible metadata changes
(#11500).egg-info files
(#11395)uvx --from tool@latest
(#11465)CHANGELOG.md is now split into separate files for each "major" version to fix rendering
(#11510)--all to uvx --reinstall message (#11535)GET on HTTP 400 when attempting to use range requests for wheel download
(#11539)uvx (#11524)tool.uv.build-constraint-dependencies
(#11585)Arc for index URLs (#11586)requirement.txt files
(#11644)uv lock --script
(#11717).env files in UV_ENV_FILE
(#11665)SmallString on Hashes (#11756)Box for Yanked on File (#11755)SmallString for the Yanked enum (#11715)uv add
(#11716)uv export (#11643)uv build
(#11593)cache-keys setting
(#11669)-vvv)
(#11758)uv tool uninstall
(#11889)include-system-site-packages in layered environments
(#11873)uv tool update-shell in PowerShell
(#11846)65001 before setting environment variables in virtual environments
(#11831)String for package name constructors
(#11768)String in deserializers (#11764)zlib-rs (again) (#11894)SmallString for filenames and URLs (#11765)no_default_groups documentation and changelog
(#11928)--constraints and --overrides in uvx
(#10207)satisfies check for uv tool run
(#11994)package = true on tool.uv.sources
(#12014)uv run
(#11888).py script
(#11623)uvx run (#11992)NO_BUILD and NO_BUILD_PACKAGE environment variables
(#11968)--user instead of --username
(#11947)uv_build package
(#11446)See the
python-build-standalone release notes
for more details.
--marker flag to uv add (#12012)[index].authenticate allowing authentication to be required on an index
(#11896)uv tool run
(#12079)include-group
(#12005)uv add failed
(#12106)uv-auth (#12077)PATH updated when the export is commented in the shellrc
(#12043)uv publish retry on network failures (#12041)uv publish to comply with WSGI PyPI server constraints
(#12111)uv python install --reinstall when the version was not previously installed
(#12124)uv_build invocation (#12058)python-versions.md
(#12112)[index].authenticate docs (#12102)CXX compiler on LinuxSee the
python-build-standalone release notes
for more details.
-c constraints in uv add
(#12209)--global default version in uv python pin
(#12115)uv pip install
(#12176)--group flag to uv pip install and uv pip compile
(#11686)File struct
(#12159)src to default cache keys (#12062)python pin --global creates parent directories if missing
(#12180)uv sync --script
(#12158)activate.bat output (#12160)BaseClientBuild to accept custom proxies
(#12232)default-groups = "all"
(#12289)--managed-python and --no-managed-python flags for toggling Python preferences
(#12246)requires-python
(#12278)Planner::build
(#12281)keyring --mode creds when authenticate = "always"
(#12316)authenticate = "always"
(#12313)UV_MANAGED_PYTHON flags
(#12345)--torch-backend to the PyTorch guide
(#12317)#keyring-provider references in alternative index docs
(#12315)--directory path in examples (#12165)--torch-backend=auto
(#12070)uv sync --check flag (#12342)uv python list
(#12375).env files in uv tool run (#12386)python find --script (#11891)--torch-backend is enabled
(#12385)--no-build (#12314)--find-links entries for pinned indexes
(#12396)--exclude-newer
(#12299)requirements.txt
(#12354)pip commands
(#12470)uv export command
(#12350)--find-links-style "flat" indexes in [[tool.uv.index]]
(#12407)-q and -qq (#12300)UV_PROJECT environment to set project directory.
(#12327)requires-python to script blocks
(#12517)uv sync (#12502)uv tree --only-group
(#12560)uv python list
(#12628)authenticate when using explicit = true
(#12631)uv add and uv remove
(#12586)python-platform in settings files
(#12592)uv build to package = false
(#12608)authenticate = always documentation
(#12498)--show-version to uv python find (#12376)--no-config warning from uv pip compile and uv pip sync
(#12642)PATH when searching for Python interpreters
(#12367)SCRIPT_PATH in relocatable activation script
(#12672)UV_PYTHON_DOWNLOADS_JSON_URL to set custom managed python sources
(#10939)pyproject.toml files in uv pip compile -o
(#12673)--offline flag for Git operations
(#12619)uv export with conflicts
(#12726)The following Python versions have been added:
See the
python-build-standalone release notes
for more details.
uv-build and uv_build aliases to uv init --build-backend
(#12776)environment.yml files
(#12669)tool.uv.sources is set in system-level configuration file
(#12757)uv init
(#12756)uv pip sync
(#12683)This release includes preliminary support for the pylock.toml file format, as standardized in
PEP 751. pylock.toml is an alternative resolution output
format intended to replace requirements.txt (e.g., in the context of uv pip compile, whereby a
"locked" requirements.txt file is generated from a set of input requirements). pylock.toml is
standardized and tool-agnostic, such that in the future, pylock.toml files generated by uv could
be installed by other tools, and vice versa.
As of this release, pylock.toml is supported in the following commands:
uv.lock to the pylock.toml format, run: uv export -o pylock.tomlpylock.toml file from a set of requirements, run:
uv pip compile -o pylock.toml requirements.inpylock.toml file, run: uv pip sync pylock.toml or
uv pip install -r pylock.tomluv pip compile (#13019)uv export support for PEP 751 (#12955)requirements.txt (verbatim) as a format on the CLI
(#12957)UV_NO_EDITABLE environment variable to set --no-editable on all invocations
(#12773)pylock.toml to uv pip install and uv pip sync
(#12992)SIGINT to child processes
(#13018)uv.lock (#12968)which git in uv init (#12893)--dry-run with --locked / --frozen for uv sync
(#12778)uv export (#12958)uv init resilient against broken git (#12895)uv run --with dependencies
(#12882)uv tool and PEP723 scripts.
(#12842)uvx binary when searching for uv binary
(#12923)SourceNotAllowed error message during Python discovery
(#13012)config-settings with example in docs
(#12947)PythonDownloadRequest parsing for partial keys
(#12925)uv-pep440
(#12836)uv run
(#13017)CC and CCX entries in sysconfig for cross-compiled aarch64 Python distributions
(#12239)UV_STACK_SIZE
(#12839)uv python list (#12915)subdirectory to Direct URL for local directories
(#12971)uv python install
(#12194)uv init
(#12870)uv python list --only-downloads and --only-installed
(#12916)--locked to uv sync in GitHub Actions guide
(#12819)"all" default-groups setting documentation
(#12963)--frozen with --locked in Docker integration guide
(#12818)python (#13051)requires-python even if not listed on the index page
(#13086)