●Change8

Migrating to uv 0.9.0

Version 0.9.0 introduces 6 breaking changes. This guide details how to update your code.

Released: 10/7/2025

6
Breaking Changes
5
Migration Steps
6
Affected Symbols

⚠️ Check Your Code

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

uv.python.installuv.venvuvxuv.builduv.tool.upgradeDocker image tags (uv:alpine, uv:debian, uv:debian-slim)

Breaking Changes

●Issue #1

Default Python version changed from 3.13 to 3.14; if no version is pinned uv will now download and use Python 3.14, which may break scripts that assume 3.13. Pin the desired version via a .python-version file or explicit version argument to avoid the change.

●Issue #2

Free‑threaded Python 3.14+ interpreters are now accepted without the previous "3.14t" opt‑in flag; the GIL‑enabled build is still preferred. Adjust any tooling that relied on the explicit opt‑in flag.

●Issue #3

Docker image tags for Python 3.14 no longer include the "-rc" suffix (e.g., python:3.14-alpine instead of python:3.14-rc-alpine). Update CI/CD pipelines that reference the old tags.

●Issue #4

The uv:alpine Docker image now uses Alpine 3.22 instead of 3.21. Pull the new image tag or use uv:alpine3.21 to retain the previous base.

●Issue #5

The uv:debian and uv:debian-slim Docker images now use Debian 13 "Trixie" instead of Debian 12 "Bookworm". Use uv:bookworm or uv:bookworm-slim to keep the older base.

●Issue #6

When a trailing '/' is supplied to `uv build` in a workspace, the output path is now correctly resolved to <workspace root>/dist/ instead of a nested child directory.

Migration Steps

  1. 1
    If you rely on a specific Python version, pin it in a .python-version file or pass the version explicitly to uv commands.
  2. 2
    Update any CI/CD scripts that reference Python 3.14 Docker images with the "-rc" suffix to the new stable tags.
  3. 3
    If you need the previous Alpine 3.21 base, switch to the image tag `uv:alpine3.21`.
  4. 4
    If you need the previous Debian 12 base, switch to the image tags `uv:bookworm` or `uv:bookworm-slim`.
  5. 5
    Review build scripts that invoke `uv build` with a trailing slash; the output location has changed but the command now works as intended.

Release Summary

uv 0.9.0 switches the default Python version to 3.14, updates Docker images, and adds free‑threaded interpreter support, while fixing several build and upgrade bugs.

Need More Details?

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

View Full Changelog