Migrating a Repo from venv to uv

Overview

Two distinct migrations hide under "switch to uv": replacing the tooling that builds a persistent venv, and deleting the persistent venv entirely in favor of stateless uv run. They fix different problems; pick deliberately.

Why move off python -m venv + pip at all

• Interpreter drift: the OS ships a Python newer than your tooling supports (e.g. ansible-core 2.18's controller ceiling is 3.13; newer distros ship 3.14). python3 -m venv silently lands on the unsupported one. .python-version + uv python install pins the interpreter, downloaded into ~/.local — no apt, no sudo.
• PEP 668: modern distros block system-wide pip install anyway.
• Machines without python3-venv and without sudo stop being blockers.

The two end states

uv-built persistent .venv — same activation workflow, faster and interpreter-pinned. Right for team repos with mixed tooling habits (discoverability: people expect a venv). Traps:

• uv venv refuses to replace an existing venv without --clear — a stale wrong-interpreter venv survives a "rebuild".
• uv pip sync can silently drop packages the requirements imply; prefer uv pip install -r.

Fully stateless uv run — no venv at all: