changelogs/0.5.x.md
Since the launch of Python version, project, and tool management capabilities back in August, we've seen extraordinary adoption of uv. We've been iterating rapidly: adding new features, fixing bugs, and improving the user experience. Despite moving quickly, stability and compatibility have been a major focus — we've made thirty releases since our last breaking change. Consequently, 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.
Use base executable to set virtualenv Python path (#8481)
Previously, uv canonicalized the path to the Python executable when setting the Python path in
created virtual environments. This behavior had several undesirable effects: it would bypass
stabilized version directories (as constructed by Homebrew) and it was not consistent with the
Python standard library's behavior. Now, uv uses the sys._base_executable path.
Use XDG (i.e. ~/.local/bin) instead of the Cargo home directory in the installer
(#8420)
Previously, uv's installer used $CARGO_HOME or ~/.cargo/bin for its target install directory.
It's been a longstanding complaint that uv uses this directory, as there's no relationship to
Cargo. Now, uv will be installed into $XDG_BIN_HOME, $XDG_DATA_HOME/../bin, or ~/.local/bin
(in that order). Note that $UV_INSTALL_DIR can always be used to override the target directory.
Discover and respect .python-version files in parent directories
(#6370)
Previously, uv only read .python-version files from the working directory. Now, uv will check
parent directories for .python-version files; however uv will not search for .python-version
files beyond project boundaries. The new behavior is better aligned with that of pyenv and Rye.
Error when disallowed settings are defined in uv.toml
(#8550)
Some settings can only be defined in the pyproject.toml. Previously, uv would ignore these
settings when present in the uv.toml. Now, uv will error to avoid confusion about why the
settings are not respected.
Implement PEP 440-compliant local version semantics (#8797)
Previously, uv's implementation of local versions (e.g., 2.0+cpu) was not compliant with the
specification due to the technical complexity of implementing the local version semantics in the
PubGrub algorithm. Thanks to the work of @ericmarkmartin, uv now has a spec-compliant
implementation. Namely, uv will now allow a request for torch==2.1.0 to install
[email protected]+cpu regardless of whether [email protected] (without a local tag) actually exists.
Treat the base Conda environment as a system environment (#7691)
Previously, uv would not distinguish between the base and other Conda environments. Now, uv uses
CONDA_DEFAULT_ENV and the names base and default to determine if an environment active via
CONDA_PREFIX is the base environment. If the base environment is active, the --system flag
must be used to mutate it.
Do not allow pre-releases when the != operator is used
(#7974)
Previously, uv would use the presence of a pre-release specifier in a version specifier as an
opt-in to allow pre-release versions during resolution. The new behavior does not allow
pre-releases when an inequals operator is used, e.g., != 2.0a1.
Prefer USERPROFILE over FOLDERID_Profile when selecting a home directory on Windows
(#8048)
This change is a side-effect of switching from the directories crate to etcetera for
determining canonical system paths. If USERPROFILE is not set, the behavior will be unchanged.
Improve interactions between color environment variables and CLI options (#8215)
Previously, uv would respect the FORCE_COLOR and NO_COLOR environment variables over the
--color flag. Now, when the --color flag is explicitly provided, uv will respect it over the
environment variables.
Make allow-insecure-host a global option
(#8476)
Previously, this option was only available in some parts of uv. Now, --allow-insecure-host can
be provided to any command. For consistency, the allow-insecure-host setting has been removed
from the [tool.uv.pip] configuration in favor of [tool.uv].
Only write .python-version files during uv init for workspace members if the version
differs (#8897)
Previously, uv would create a .python-version file for workspace members during uv init. Now,
uv will only do so if the version differs from the .python-version file in the workspace root
since uv will respect .python-version files in parent directories.
uv tree --outdated (#8893)pip list --outdated (#8872); on URL and path requirements
(#8835)uv cache clean (#8857)uv lock (#8867)--resolution-mode=lowest-direct
(#8839)uv python install docs to use an existing PyPy version
(#8845)--verbose with RUST_LOG
(#8858)riscv64
(#8934)uv pip list --outdated
(#8939)--index-url in uv pip list (#8942)--with (#8946)~/.cargo/bin
(#8936)--no-system from uv pip tree CLI (#9040)uv.toml
(#8695)uv python install
(#8695)--no-build to validate lock (#9024).venv in uv add --frozen and uv add --no-sync
(#8980)uv add
(#9109)--resolution-strategy in error message output
(#8971)uv run
(#8933)uv.lock changes when uv add fails (#9030).exe
(#9099)uv add (#9097)--with requirements
(#9089)glob-walkdir implementation
(#9013).env file example in docs (#9064)--resolution in docs (#8968)value_type consistently
(#9017)[[index]] API in configuration example (#9065)This release includes support for conflicting optional dependencies and dependency groups in the uv resolver, including the ability to specify dependency sources (like index assignment) on a per-extra or per-group basis.
For example, you can now select CPU-only vs. GPU-enabled PyTorch builds at runtime by defining
conflicting extras in a pyproject.toml, and assigning different extras to different PyTorch
indexes:
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.12.0"
[project.optional-dependencies]
# Include `torch` whenever `--extra cpu` or `--extra gpu` is provided.
cpu = ["torch>=2.5.1"]
gpu = ["torch>=2.5.1"]
[tool.uv]
# But allow `cpu` and `gpu` to choose conflicting versions of `torch`.
conflicts = [[{ extra = "cpu" }, { extra = "gpu" }]]
[tool.uv.sources]
torch = [
# With `--extra cpu`, pull PyTorch from the CPU-only index.
{ index = "pytorch-cpu", extra = "cpu", marker = "platform_system != 'Darwin'" },
# With `--extra gpu`, pull PyTorch from the GPU-enabled index.
{ index = "pytorch-gpu", extra = "gpu" },
]
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
[[tool.uv.index]]
name = "pytorch-gpu"
url = "https://download.pytorch.org/whl/cu124"
explicit = true
See the PyTorch documentation for more.
uv tool install --force to imply --reinstall-package <name>
(#9074)--verify-hashes on by default (#9170)zlib-rs on all platforms (#9202)--frozen --package in legacy non-[project] workspaces
(#9215)[[tool.uv.index]] in PEP 723 scripts
(#9208)--index <name>=<url> syntax to index documentation
(#9139)include = "dev" with tool.uv.dev-dependencies
(#9173)true
(#9169)git is not found (#9206)--all-groups to uv sync, uv run, uv export, and uv tree
(#8892)uv tree --outdated and uv pip list --outdated
(#9284)build-system.requires
(#9273)reqwest errors (#9253)uv export output (#9237)--index and --default-index from command header
(#9288)uv tool upgrade (#9375)--no-sync and --frozen in uv run
(#9400)--target and --prefix
(#9373)--no-extra flag and setting (#9387)uv export --prune (#9389)license-files metadata during uv publish
(#9442)--target and --prefix
(#9371)--output-file is empty (#9417)tool.uv.dependency-metadata.[].version schema
(#9468)--compile is passed to an install operation
(#9378)--upgrade, --no-upgrade, and --upgrade-package from uv tool upgrade
(#9318)--all-groups --no-dev
(#9300)uv export
(#9365)scikit-build (instead of scikit-build-core)
(#9320)pyproject.toml in project concept documentation
(#9298)--no-progress option in related environment variable
(#9357)--dry-run to uv pip uninstall (#9557)--constraints and --overrides in uv tool install
(#9547)uv publish
(#8827).python-version pin is incompatible with the project
(#9590)tool.uv.sources
(#9482)requires-python
(#9529)uv python install --default (#8650)include / exclude (#9525)check-url available in configuration files
(#9032)String in marker evaluation (#9598)uv-pep508: Add more methods for simplifying extra-related expressions
(#9469)file: URLs to include package names (#9493)uv tool list
(#9605)manylinux_compatible with --python-platform
(#9526)pip compile -r pyproject.toml
(#9535)--refresh-package flag mentioned as --refresh-dependency
(#9486)run.md (#9527)uv pip behavior in build system note
(#9586)uv build --no-build-logs option (#9642)uv build
(#9633)3.9.21, 3.10.16, 3.11.11, 3.12.8,
and 3.13.1 (#9696)uv init (#9661)--list option (#9610)uv export / uv pip compile
(#9648)python list
(#9669)Ord and PartialOrd without origin for Requirement
(#9624)uv.lock (#9677)build-essentials note to build failures doc
(#9641)uv python pin without a REQUEST argument
(#9631)uv python pin reference docs (#9630)This release does not include the powerpc64le-unknown-linux-musl target due to a build issue.
See #9793 for details. If this change affects you,
please file an issue with your use-case.
--install-dir to to uv python install and uninstall commands
(#7920)--show-urls and --only-downloads to uv python list
(#8062)uv python list --all-arches (#9782)uv run --gui-script flag for running Python scripts with pythonw.exe
(#9152)--gui-script on Unix (#9787)pyw files on Unix (#9759)project.dependencies and tool.uv.sources
(#9718)uv publish --index <name> (#9694)--locked and --frozen as --check operations for uv lock
(#9662).cache -> .temp
(#9756)uv tool uninstall uv on Windows (#8963)git+ prefixes
(#9789)pyproject.toml requirements
(#9704)uv export (#9751)--no-build when static metadata is available
(#9785).egg-info files
(#9760). prefixed directories during managed Python installation discovery
(#9786)--project is specified
(#9709)--find-links as relative URLs
(#9720)python3.13.exe et al (#9679)uv python install
(#9706)requires-python requirements
(#9827)sysconfig data at install time (#9857)-isysroot when patching sysconfig (#9860)panic!() when current directory does not exist
(#9876)uv help python on invalid install requests
(#9820)uv tool upgrade
(#9870)--fork-strategy setting (#9887)sysconfig values such as AR at ar install time
(#9905)sysconfig values such as clang to cc at install time
(#9916)--native-tls in pip compile header (#9913)uv remove (#9959)uv remove dependency hints
(#9960)version field
(#9912)fork-strategy setting
(#9931)pypy from top-level pin example (#9896)python-build-standalone to reflect the transferred project
(#9977)powershell and cmd.exe
(#9903)uv-lock and uv-export pre-commit hooks
(#9872)platform_system to sys_platform (#9949)copy_atomic and write_atomic
(#10026)python-build-standalone 20241219metadata_directory already contains dist-info directory
(#10005)--script to be provided with uv run -
(#10035)uv run arguments when reading from stdin
(#10034)first-match
(#10036)uv python install --preview to the documentation
(#10010)uv python install --default note about multiple requests
(#10011)first-match
(#10038)UV_INSTALL_DIR directions on Windows
(#9507)uv export for non-project workspaces
(#10144)uv-build Requires-Dist metadata
(#10110)shutil.which for the build backend (#10028)uv.lock
(#10068)uv add
(#10095)uv init CLI (#10124)uv tree (#10149)reqwest (#10178)" (#10187)--exact flag to uv run (#10198)--outdated support to uv pip tree (#10199)--python-platform
(#10217)--description in uv init
(#10209)BTreeMap::range to avoid iterating over unnecessary versions
(#10266)uv init
(#10246)uv venv and uv tool
(#10206)The managed Python distributions have been updated, including:
See the
python-build-standalone release notes
for more details.
FORCE_COLOR environment variable (#10315)uv lock
(#10307)--upgrade is provided
(#10097)uv add (#10329)exclude-newer only allows full timestamps in settings documentation
(#9135)--no-project comment (#10331)uv remove (#10338)VersionSmall (#10385)requirements_for_extra (#10348)zlib-ng on x86 platforms (#10365)[u64; 4] from small version to move Arc to full version
(#10345)Dist from 352 to 288 bytes (#10389)serde_json::from_reader
(#10341)uv self
(#10374)This release includes support for generating lockfiles from scripts based on inline metadata, as defined in PEP 723.
By default, scripts remain unlocked, and must be locked explicitly with
uv lock --script /path/to/script.py, which will generate a lockfile adjacent to the script (e.g.,
script.py.lock). Once generated, the lockfile will be respected (and updated, if necessary) across
uv run --script, uv add --script, and uv remove --script invocations.
This release also includes support for uv export --script and uv tree --script. Both commands
support PEP 723 scripts with and without accompanying lockfiles.
uv run
(#10136)uv add --script
(#10145)uv remove --script
(#10162)--script support to uv export for PEP 723 scripts
(#10160)--script support to uv tree for PEP 723 scripts
(#10159)ls alias to uv {tool, python, pip} list
(#10240)--with-requirements from stdin in uv add and uv run
(#10447)requirements.txt options
(#10420).to_string() call (#10419)ArcStr for marker values (#10453)ArcStr for package, extra, and group names
(#10475)matches! rather than contains in requirements.txt parsing
(#10423)UV_FIND_LINKS delimiter to split on commas
(#10477)uv tool list output when tool environment is broken
(#10409)requires-python when installing tools
(#10401)venv activate scripts
(#10397)uv lock --script to the docs (#10414)uv remove when only comments exist
(#10484)pip freeze --path (#10488)uv run <script.py>
(#10588)--native-tls on SSL errors (#10605)--output-format=json support to uv python list
(#10596)The managed Python distributions have been updated, including:
libedit updated from 20210910-3.1 -> 20240808-3.1tcl/tk updated from 8.6.12 -> 8.6.14 (for all Python versions on Unix, only for Python
3.14 on Windows)See the
python-build-standalone release notes
for more details.
WheelFilename to 48 bytes (#10583)import re from entrypoint wrapper scripts
(#10627)ArcStr in verbatim URL (#10600)memchr for wheel parsing (#10620)uv python install on Windows
(#10639)pyproject.toml path for parse errors in uv venv
(#10553)setuptools and wheel as seed packages in uv sync on Python 3.12
(#10572)python install
(#10629)--config-settings are present
(#10578)build-system from example workspace rot
(#10636)UV_VENV_SEED environment variable (#10715)requires-python marker with disjunctions
(#10704)requirements.txt
(#10690)SyntaxWarning compatibility note to bytecode compilation docs
(#10701)MACOSX_DEPLOYMENT_TARGET to the --python-platform documentation
(#10698)pyproject.toml from GitHub API (#10765)Requires-Dist mismatches
(#10797)commit_id and requested_revision in direct_url.json
(#10862)--frozen and --locked in uv run --script
(#10840)find-links paths relative to the configuration file
(#10827)--locked and --upgrade are conflicting
(#10836)cargo-dist 0.28.0; improves several installer behaviors
(#10884)= for editables in requirements.txt
(#10954)128+n) exit codes for uv run and uv tool run on Unix
(#10781)PATH
(#11030)--editable flag on non-directory requirements
(#10994)--no-sources for uv pip install workspace discovery
(#11003)JEMALLOC_SYS_WITH_LG_PAGE=16 in ARM Docker builds
(#10943)riscv64 Python downloads to allow install on riscv64gc
(#10937)tool.uv.sources.(package).workspace with other
options (#11013)uv run (#11009)SECURITY policy (#11035)Requires-Python upper bound behavior to the docs
(#10964)uv add -r (#10926)requires-python rules in resolver documentation
(#10993)--no-sources documentation
(#10995)uvx python (#11076)--no-dev --invert in uv tree (#11068)uv python install --reinstall to reinstall all previous versions
(#11072)--build-backend when --backend is passed to uv init
(#10958)--script is passing a non-PEP 723 script
(#11118)<index>/simple to <index>/... endpoints
(#11074)uv sync (#11075)RUST_LOG documentation (#10053)--no-deps description (#11073)sys_platform in lieu of platform_system in PyTorch docs
(#11113)uv pip install with --extra or --all-extras and invalid sources
(#11193)tokio-tar fork (#11174).clone() (#11127)_GLibCVersion tuple in uv-python crate
(#11122)pip install example in troubleshooting guide
(#11194)VIRTUAL_ENV in Jupyter kernels (#11155)PATH
(#11218)--allow-insecure-host
(#11210)last updated to documentation (#11164)--bare option to uv init (#11192)VIRTUAL_ENV in project commands via --active
(#11189)VIRTUAL_ENV warning to be silenced with --no-active
(#11251)The managed Python distributions have been updated, including:
See the
python-build-standalone release notes
for more details.
--all-groups and --no-default-groups flags
(#11224)mkdocs.public.yml into the template
(#11246)The managed PyPy distributions have been updated for PyPy v7.3.18, which includes:
See the PyPy release for more details.
NO_BINARY and NO_BINARY_PACKAGE environment variables
(#11399)simple/
(#11336)@ requests for tools (#11335)astral-tokio-tar to v0.5.1 (#11359)eprintln in trampoline warnings
(#11295)torch packages when using conflicting extras
(#11323)uv tool install --editable (#11280)uv sync --script (#11361)+local suffixes
(#11429)uvx and uv tool install requests
(#11345)uv run (#11386)The managed Python distributions have been updated, including:
See the
python-build-standalone release notes
for more details.
--python <dir> requests to match existing environments if sys.executable is the same
file (#11290)--dry-run mode
(#11427)<name> over <name>/__main__.py
(#11431)