uv python pin: Pin a Project Python Version
uv python pin writes a .python-version file recording which interpreter the project should use.
uv python pin makes Python version selection reproducible. The committed .python-version file means every developer and every CI run uses the same interpreter.
What it does
uv python pin writes (or updates) the .python-version file in the project directory. uv then honors that pin when creating environments, running uv run, or syncing, downloading the interpreter if it is a managed version and not yet present.
Common usage
uv python pin 3.12
uv python pin 3.12.4
uv python pin pypy@3.10
cat .python-versionOptions
| Argument | What it does |
|---|---|
| <version> | The version request to write, e.g. 3.12 or 3.12.4 |
| --resolved | Write the fully resolved interpreter path/version |
| (no arg) | Print the currently pinned version |
In CI
Commit .python-version so jobs do not depend on the runner default Python. uv reads it automatically; you rarely need setup-python alongside uv. If the pinned version is a managed build, allow uv to download it or pre-run uv python install in a cached step.
Common errors in CI
"error: No interpreter found for Python <version>" means the pinned version is not installed and downloads are disabled (UV_PYTHON_DOWNLOADS=never); install it or allow downloads. A pin like 3,12 yields "Failed to parse Python version". A stale .python-version pointing at an uninstalled patch release fails until you re-pin to an available one.