uv python pin

Pin to a specific Python version

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 cpython@3.10.

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
• cpython@3.11 - 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. cpython@3.12
• <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 pypy@3.10

Creates .python-version with pypy@3.10.

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 cpython@3.12
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.

See Also

• uv python install - Download and install Python versions
• uv python find - Find a Python installation
• uv python list - List available Python installations
• uv python uninstall - Uninstall Python versions