> ## 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 install

> Download and install Python versions

## Synopsis

```bash theme={null}
uv python install [OPTIONS] [TARGETS]...
```

## Description

Download and install Python versions.

Supports CPython and PyPy. CPython distributions are downloaded from the Astral `python-build-standalone` project. PyPy distributions are downloaded from `python.org`. The available Python versions are bundled with each uv release. To install new Python versions, you may need to upgrade uv.

Python versions are installed into the uv Python directory, which can be retrieved with `uv python dir`.

By default, Python executables are added to a directory on the path with a minor version suffix, e.g., `python3.13`. To install `python3` and `python`, use the `--default` flag. Use `uv python dir --bin` to see the target directory.

Multiple Python versions may be requested.

See `uv help python` to view supported request formats.

## Arguments

### `[TARGETS]...`

The Python version(s) to install.

If not provided, the requested Python version(s) will be read from:

1. The `UV_PYTHON` environment variable
2. `.python-versions` or `.python-version` files
3. If none of the above are present, uv will check if it has installed any Python versions
4. If not, it will install the latest stable version of Python

See `uv help python` to view supported request formats.

**Environment variable:** `UV_PYTHON`

## Options

### Installation Directory

#### `-d, --install-dir <INSTALL_DIR>`

The directory to store the Python installation in.

If provided, `UV_PYTHON_INSTALL_DIR` will need to be set for subsequent operations for uv to discover the Python installation.

See `uv python dir` to view the current Python installation directory.

* **Type:** Path
* **Default:** `~/.local/share/uv/python`
* **Environment variable:** `UV_PYTHON_INSTALL_DIR`

### Executable Installation

#### `--bin`

Install a Python executable into the `bin` directory.

This is the default behavior. If this flag is provided explicitly, uv will error if the executable cannot be installed.

This can also be set with `UV_PYTHON_INSTALL_BIN=1`.

See `UV_PYTHON_BIN_DIR` to customize the target directory.

* **Conflicts with:** `--no-bin`

#### `--no-bin`

Do not install a Python executable into the `bin` directory.

This can also be set with `UV_PYTHON_INSTALL_BIN=0`.

* **Conflicts with:** `--bin`, `--default`

### Registry (Windows)

#### `--registry`

Register the Python installation in the Windows registry.

This is the default behavior on Windows. If this flag is provided explicitly, uv will error if the registry entry cannot be created.

This can also be set with `UV_PYTHON_INSTALL_REGISTRY=1`.

* **Conflicts with:** `--no-registry`

#### `--no-registry`

Do not register the Python installation in the Windows registry.

This can also be set with `UV_PYTHON_INSTALL_REGISTRY=0`.

* **Conflicts with:** `--registry`

### Installation Behavior

#### `-r, --reinstall`

Reinstall the requested Python version, if it's already installed.

By default, uv will exit successfully if the version is already installed.

#### `-f, --force`

Replace existing Python executables during installation.

By default, uv will refuse to replace executables that it does not manage.

Implies `--reinstall`.

#### `-U, --upgrade`

Upgrade existing Python installations to the latest patch version.

By default, uv will not upgrade already-installed Python versions to newer patch releases. With `--upgrade`, uv will upgrade to the latest available patch version for the specified minor version(s).

If the requested versions are not yet installed, uv will install them.

This option is only supported for minor version requests, e.g., `3.12`; uv will exit with an error if a patch version, e.g., `3.12.2`, is requested.

#### `--default`

Use as the default Python version.

By default, only a `python{major}.{minor}` executable is installed, e.g., `python3.10`. When the `--default` flag is used, `python{major}`, e.g., `python3`, and `python` executables are also installed.

Alternative Python variants will still include their tag. For example, installing 3.13+freethreaded with `--default` will include `python3t` and `pythont` instead of `python3` and `python`.

If multiple Python versions are requested, uv will exit with an error.

* **Conflicts with:** `--no-bin`

### Mirror URLs

#### `--mirror <MIRROR>`

Set the URL to use as the source for downloading Python installations.

The provided URL will replace `https://github.com/astral-sh/python-build-standalone/releases/download` in, e.g., `https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`.

Distributions can be read from a local directory by using the `file://` URL scheme.

* **Type:** URL

#### `--pypy-mirror <PYPY_MIRROR>`

Set the URL to use as the source for downloading PyPy installations.

The provided URL will replace `https://downloads.python.org/pypy` in, e.g., `https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`.

Distributions can be read from a local directory by using the `file://` URL scheme.

* **Type:** URL

#### `--python-downloads-json-url <PYTHON_DOWNLOADS_JSON_URL>`

URL pointing to JSON of custom Python installations.

* **Type:** String

### Bytecode Compilation

#### `--compile-bytecode`

Compile Python's standard library to bytecode after installation.

By default, uv does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is important, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times and some additional disk space for faster start times.

When enabled, uv will process the Python version's `stdlib` directory. It will ignore any compilation errors.

* **Aliases:** `--compile`
* **Environment variable:** `UV_COMPILE_BYTECODE`
* **Conflicts with:** `--no-compile-bytecode`

#### `--no-compile-bytecode`

Do not compile Python's standard library to bytecode.

* **Aliases:** `--no-compile`
* **Conflicts with:** `--compile-bytecode`

## 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`

## Examples

### Install the latest Python version

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

### Install a specific minor version

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

### Install a specific patch version

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

### Install multiple versions

```bash theme={null}
uv python install 3.11 3.12 3.13
```

### Install PyPy

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

### Install with default executables

```bash theme={null}
uv python install 3.12 --default
```

This installs `python3.12`, `python3`, and `python` executables.

### Install from a custom mirror

```bash theme={null}
uv python install 3.12 --mirror https://my-mirror.example.com/python
```

### Install with bytecode compilation

```bash theme={null}
uv python install 3.12 --compile-bytecode
```

### Reinstall an existing version

```bash theme={null}
uv python install 3.12 --reinstall
```

### Upgrade to latest patch version

```bash theme={null}
uv python install 3.12 --upgrade
```

Upgrades Python 3.12.x to the latest available 3.12 patch release.

### Install without executables

```bash theme={null}
uv python install 3.12 --no-bin
```

### Force replace existing executables

```bash theme={null}
uv python install 3.12 --force
```

## Output Format

### Successful Installation

```
Downloading CPython 3.12.4
Installed Python 3.12.4 in 2.3s
 + cpython-3.12.4-macos-aarch64-none
```

### Already Installed

```
Python 3.12.4 is already installed
```

### With --reinstall

```
Reinstalling Python 3.12.4
Installed Python 3.12.4 in 2.1s
 + cpython-3.12.4-macos-aarch64-none
```

### Multiple Versions

```
Downloading CPython 3.11.9
Downloading CPython 3.12.4
Installed 2 versions in 4.2s
 + cpython-3.11.9-macos-aarch64-none
 + cpython-3.12.4-macos-aarch64-none
```

## See Also

* [`uv python list`](python-list.mdx) - List available Python installations
* [`uv python uninstall`](python-uninstall.mdx) - Uninstall Python versions
* [`uv python find`](python-find.mdx) - Find a Python installation
* [`uv python pin`](python-pin.mdx) - Pin to a specific Python version