●Change8

Migrating to uv 0.10.0

Version 0.10.0 introduces 11 breaking changes. This guide details how to update your code.

Released: 2/5/2026

11
Breaking Changes
8
Migration Steps
10
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

uv venvuv auth loginuv auth tokenuv tool runuv tool installuv python pinuv formatuv add --boundsuv workspace diruv workspace list

Breaking Changes

●Issue #1

The uv venv command now requires the --clear flag to remove an existing virtual environment, instead of prompting or removing silently. Opt out by passing --clear or setting UV_VENV_CLEAR=1.

●Issue #2

uv now errors if multiple indexes in configuration are marked with default = true. Remove default = true from all but one index.

●Issue #3

uv now errors if an explicit index defined in [tool.uv.sources] is unnamed. Add a name to the explicit index or remove the entry.

●Issue #4

uv python install now names alternative Python executables (PyPy, GraalPy, Pyodide) using their implementation name (e.g., pypy3.10) instead of python3.10, to prevent conflicts with CPython.

●Issue #5

uv tool run and uv tool install now respect the global Python version pin set via uv python pin --global when no explicit version is requested. To opt out, provide an explicit --python flag.

●Issue #6

Docker images for Debian Bookworm, Alpine 3.21, and Python 3.8 have been removed. Use uv:debian or uv:trixie instead of uv:bookworm, uv:alpine3.22 instead of uv:alpine3.21, and a newer Python version.

●Issue #7

Pre-built binaries for PPC64 (big endian) architecture are no longer provided. Building from source is still supported.

●Issue #8

The activate.csh script is no longer generated when creating relocatable virtual environments using uv venv --relocatable, as it contained hardcoded paths.

●Issue #9

uv now errors if multiple stored credentials match a host URL during authentication (e.g., uv auth token) instead of silently picking the first match. Specify the username using uv auth token --username <username>.

●Issue #10

Changing the exclude-newer setting no longer causes package versions to be upgraded, ignoring the lockfile entirely, unless --upgrade or --upgrade-package is used.

●Issue #11

uv format now uses Ruff 0.15.0, adopting the 2026 style guide, which will likely change code formatting. Opt out by specifying an older Ruff version, e.g., uv format --version 0.14.14.

Migration Steps

  1. 1
    If you rely on uv venv removing existing environments non-interactively, add the --clear flag or set the UV_VENV_CLEAR=1 environment variable.
  2. 2
    Review your index configuration and ensure only one index has default = true.
  3. 3
    Ensure all explicit indexes defined in [tool.uv.sources] have a name.
  4. 4
    If using uv tool run or uv tool install, be aware that the global Python pin is now respected; provide --python if you need a different version.
  5. 5
    If using removed Docker images (uv:bookworm, uv:alpine3.21, uv:python3.8-*), update to the recommended alternatives (uv:debian, uv:trixie, uv:alpine3.22, or newer Python versions).
  6. 6
    If you use uv auth token and have multiple credentials for one host, specify the username explicitly.
  7. 7
    If you need to force package version upgrades after changing exclude-newer, use --upgrade or --upgrade-package.
  8. 8
    If you rely on the formatting produced by uv format, review changes introduced by Ruff 0.15.0 and the 2026 style guide, or pin to an older Ruff version if necessary.

Release Summary

This release stabilizes several preview features, including Python version management and workspace utilities, while introducing several breaking changes related to configuration validation and virtual environment removal behavior.

Need More Details?

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

View Full Changelog