uv python pin

Synopsis

uv python pin [OPTIONS] [REQUEST]

Description

Pin to a specific Python version. Writes the pinned Python version to a .python-version file, which is used by other uv commands to determine the required Python version. If no version is provided, uv will look for an existing .python-version file and display the currently pinned version. If no .python-version file is found, uv will exit with an error. See uv help python to view supported request formats.

Arguments

`[REQUEST]`

The Python version request. uv supports more formats than other tools that read .python-version files, i.e., pyenv. If compatibility with those tools is needed, only use version numbers instead of complex requests such as [email protected]. If no request is provided, the currently pinned version will be shown. See uv help python to view supported request formats. Examples:

3.12 - Pin to Python 3.12
3.12.4 - Pin to specific patch version
[email protected] - Pin to CPython 3.11
>=3.10 - Pin with version specifier (not compatible with pyenv)

Options

Pin Behavior

`--resolved`

Write the resolved Python interpreter path instead of the request. Ensures that the exact same interpreter is used. This option is usually not safe to use when committing the .python-version file to version control.

Conflicts with: --no-resolved

Example:

uv python pin 3.12 --resolved

Writes /Users/user/.local/share/uv/python/cpython-3.12.8-macos-aarch64-none/bin/python3.12 instead of 3.12.

`--no-resolved`

Write the request instead of the resolved path. This is the default behavior.

Conflicts with: --resolved

Validation

`--no-project`

Avoid validating the Python pin is compatible with the project or workspace. By default, a project or workspace is discovered in the current directory or any parent directory. If a workspace is found, the Python pin is validated against the workspace’s requires-python constraint. Aliases: --no-workspace

Scope

`--global`

Update the global Python version pin. Writes the pinned Python version to a .python-version file in the uv user configuration directory:

Linux/macOS: $XDG_CONFIG_HOME/uv or $HOME/.config/uv
Windows: %APPDATA%/uv

When a local Python version pin is not found in the working directory or an ancestor directory, this version will be used instead.

Removal

`--rm`

Remove the Python version pin.

Conflicts with: request, --resolved

Example:

uv python pin --rm

Deletes the .python-version file.

Version Request Formats

The following Python version request formats are supported:

<version> e.g. 3, 3.12, 3.12.3
<version-specifier> e.g. >=3.12,<3.13
<version><short-variant> e.g., 3.13t, 3.12.0d
<version>+<variant> e.g., 3.13+freethreaded, 3.12.0+debug
<implementation> e.g. cpython or cp
<implementation>@<version> e.g. [email protected]
<implementation><version> e.g. cpython3.12 or cp312
<implementation><version-specifier> e.g. cpython>=3.12,<3.13
<implementation>-<version>-<os>-<arch>-<libc> e.g. cpython-3.12.3-macos-aarch64-none

Note: For compatibility with pyenv, use only simple version numbers like 3.12 or 3.12.4.

File Format

The .python-version file contains a single line with the Python version:

3.12

With --resolved, it contains the full path:

/Users/user/.local/share/uv/python/cpython-3.12.8-macos-aarch64-none/bin/python3.12

Output Format

Pinning a Version

uv python pin 3.12

Pinned Python 3.12 to `.python-version`

Showing Current Pin

uv python pin

3.12

No Pin Found

uv python pin

error: No `.python-version` file found in current directory or any parent directory

Removing Pin

uv python pin --rm

Removed `.python-version`

Validation Error

# In a project with requires-python = ">=3.11"
uv python pin 3.10

error: Python 3.10 does not satisfy the project's `requires-python` constraint: >=3.11

Examples

Pin to a minor version

uv python pin 3.12

Creates .python-version with 3.12.

Pin to a specific patch

uv python pin 3.12.4

Creates .python-version with 3.12.4.

Pin to PyPy

uv python pin [email protected]

Creates .python-version with [email protected].

Pin with resolved path

uv python pin 3.12 --resolved

Writes the full path to the interpreter instead of the version number.

Show current pin

uv python pin

Displays the contents of .python-version.

Remove pin

uv python pin --rm

Deletes the .python-version file.

Set global pin

uv python pin 3.12 --global

Writes to ~/.config/uv/.python-version (or equivalent on your OS).

Pin without project validation

uv python pin 3.10 --no-project

Skips checking compatibility with pyproject.toml.

Pin for pyenv compatibility

# Use simple version number for pyenv compatibility
uv python pin 3.12.4

Pin with version specifier (uv-only)

uv python pin ">=3.11,<3.14"

Not compatible with pyenv, but works with uv.

Use Cases

Project Python version

# Initialize a new project with Python 3.12
uv init my-project
cd my-project
uv python pin 3.12
uv sync

Team consistency

# Ensure all team members use the same Python version
uv python pin 3.12.4
git add .python-version
git commit -m "Pin Python to 3.12.4"

Team members running uv sync will use Python 3.12.4.

Multiple projects with different versions

# Project A uses Python 3.11
cd ~/projects/project-a
uv python pin 3.11

# Project B uses Python 3.12
cd ~/projects/project-b
uv python pin 3.12

uv automatically uses the correct version based on the current directory.

Migration to newer Python

# Currently on 3.11
cat .python-version  # 3.11

# Install 3.12
uv python install 3.12

# Update pin
uv python pin 3.12

# Recreate environment
rm -rf .venv
uv sync

Global default Python

# Set Python 3.12 as global default
uv python pin 3.12 --global

# All projects without their own .python-version will use 3.12
cd ~/new-project
uv venv  # Uses Python 3.12

Exact interpreter pinning (CI/CD)

# Pin to exact interpreter path for reproducibility
uv python install 3.12.4
uv python pin 3.12.4 --resolved

Ensures the exact same Python binary is used every time.

Check and update pin

# Check current pin
current=$(uv python pin)
echo "Currently pinned to: $current"

# Update to latest patch of same minor version
uv python install 3.12  # Gets latest 3.12.x
uv python pin 3.12

Temporary pin override

# .python-version says 3.11, but test with 3.12
uv run --python 3.12 pytest

# Don't change the pin permanently
cat .python-version  # Still 3.11

Clean slate

# Remove pin and let uv choose
uv python pin --rm

# uv will use system Python or auto-install latest
uv sync

Compatibility Notes

pyenv Compatibility

pyenv only supports simple version numbers in .python-version:

# Compatible with pyenv
uv python pin 3.12
uv python pin 3.12.4

# NOT compatible with pyenv
uv python pin [email protected]
uv python pin ">=3.11"
uv python pin 3.12 --resolved

If you need to share .python-version files with pyenv users, use only version numbers.

Version Control

Recommended: Commit .python-version to version control

git add .python-version
git commit -m "Pin Python version"

Not recommended: Commit resolved paths (--resolved) Resolved paths are machine-specific and will break on other systems.

Overview

Project Commands

Python Management

Tool Commands

Pip Interface

Build & Publish

Environment

Cache & Maintenance

​Synopsis

​Description

​Arguments

​[REQUEST]

​Options

​Pin Behavior

​--resolved

​--no-resolved

​Validation

​--no-project

​Scope

​--global

​Removal

​--rm

​Version Request Formats

​File Format

​Output Format

​Pinning a Version

​Showing Current Pin

​No Pin Found

​Removing Pin

​Validation Error

​Examples

​Pin to a minor version

​Pin to a specific patch

​Pin to PyPy

​Pin with resolved path

​Show current pin

​Remove pin

​Set global pin

​Pin without project validation

​Pin for pyenv compatibility

​Pin with version specifier (uv-only)

​Use Cases

​Project Python version

​Team consistency

​Multiple projects with different versions

​Migration to newer Python

​Global default Python

​Exact interpreter pinning (CI/CD)

​Check and update pin

​Temporary pin override

​Clean slate

​Compatibility Notes

​pyenv Compatibility

​Version Control

​See Also

Build docs developers (and LLMs) love