> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# uv python pin

> Pin to a specific Python version

## Synopsis

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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

```bash theme={null}
uv python pin 3.12
```

```
Pinned Python 3.12 to `.python-version`
```

### Showing Current Pin

```bash theme={null}
uv python pin
```

```
3.12
```

### No Pin Found

```bash theme={null}
uv python pin
```

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

### Removing Pin

```bash theme={null}
uv python pin --rm
```

```
Removed `.python-version`
```

### Validation Error

```bash theme={null}
# 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

```bash theme={null}
uv python pin 3.12
```

Creates `.python-version` with `3.12`.

### Pin to a specific patch

```bash theme={null}
uv python pin 3.12.4
```

Creates `.python-version` with `3.12.4`.

### Pin to PyPy

```bash theme={null}
uv python pin pypy@3.10
```

Creates `.python-version` with `pypy@3.10`.

### Pin with resolved path

```bash theme={null}
uv python pin 3.12 --resolved
```

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

### Show current pin

```bash theme={null}
uv python pin
```

Displays the contents of `.python-version`.

### Remove pin

```bash theme={null}
uv python pin --rm
```

Deletes the `.python-version` file.

### Set global pin

```bash theme={null}
uv python pin 3.12 --global
```

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

### Pin without project validation

```bash theme={null}
uv python pin 3.10 --no-project
```

Skips checking compatibility with `pyproject.toml`.

### Pin for pyenv compatibility

```bash theme={null}
# Use simple version number for pyenv compatibility
uv python pin 3.12.4
```

### Pin with version specifier (uv-only)

```bash theme={null}
uv python pin ">=3.11,<3.14"
```

Not compatible with `pyenv`, but works with uv.

## Use Cases

### Project Python version

```bash theme={null}
# Initialize a new project with Python 3.12
uv init my-project
cd my-project
uv python pin 3.12
uv sync
```

### Team consistency

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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)

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# .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

```bash theme={null}
# 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`:

```bash theme={null}
# 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

```bash theme={null}
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`](python-install.mdx) - Download and install Python versions
* [`uv python find`](python-find.mdx) - Find a Python installation
* [`uv python list`](python-list.mdx) - List available Python installations
* [`uv python uninstall`](python-uninstall.mdx) - Uninstall Python versions