Skip to main content

​
Synopsis

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. [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

​
Examples

​
Install the latest Python version

uv python install

​
Install a specific minor version

uv python install 3.12

​
Install a specific patch version

uv python install 3.12.4

​
Install multiple versions

uv python install 3.11 3.12 3.13

​
Install PyPy

uv python install [email protected]

​
Install with default executables

uv python install 3.12 --default
This installs python3.12, python3, and python executables.

​
Install from a custom mirror

uv python install 3.12 --mirror https://my-mirror.example.com/python

​
Install with bytecode compilation

uv python install 3.12 --compile-bytecode

​
Reinstall an existing version

uv python install 3.12 --reinstall

​
Upgrade to latest patch version

uv python install 3.12 --upgrade
Upgrades Python 3.12.x to the latest available 3.12 patch release.

​
Install without executables

uv python install 3.12 --no-bin

​
Force replace existing executables

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

Build docs developers (and LLMs) love

Get started for freeTalk to us