uv/docs/concepts/python-versions.md

Python versions

A Python version is composed of a Python interpreter (i.e. the python executable), the standard library, and other supporting files. It is common for an operating system to come with a Python version installed.

Requesting a version

uv will automatically download a Python version if it cannot be found.

For example, when creating a virtual environment:

uv venv --python 3.11.6

uv will ensure that Python 3.11.6 is available — downloading and installing it if necessary — then create the virtual environment with it.

Many Python version request formats are supported:

• <version> e.g. 3, 3.12, 3.12.3
• <version-specifier> e.g. >=3.12,<3.13
• <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

Installing a Python version

Sometimes it is preferable to install the Python versions before they are needed.

uv bundles a list of downloadable CPython and PyPy distributions for macOS, Linux, and Windows.

To install a Python version at a specific version:

uv python install 3.12.3

To install the latest patch version:

uv python install 3.12

To install a version that satisfies constraints:

uv python install '>=3.8,<3.10'

To install multiple versions:

uv python install 3.9 3.10 3.11

Project Python versions

By default uv python install will verify that a managed Python version is installed or install the latest version.

However, a project may define a .python-version file specifying the default Python version to be used. If present, uv will install the Python version listed in the file.

Alternatively, a project that requires multiple Python versions may also define a .python-versions file. If present, uv will install all of the Python versions listed in the file. This file takes precedence over the .python-version file.

uv will also respect Python requirements defined in a pyproject.toml file during project command invocations.

Viewing available Python versions

To list installed and available Python versions:

uv python list

By default, downloads for other platforms and old patch versions are hidden.

To view all versions:

uv python list --all-versions

To view Python versions for other platforms:

uv python list --all-platforms

To exclude downloads and only show installed Python versions:

uv python list --only-installed

Adjusting Python version preferences

By default, uv will attempt to use Python versions found on the system and only download managed interpreters when necessary. However, It's possible to adjust uv's Python version selection preference with the python-preference option.

• only-managed: Only use managed Python installations; never use system Python installations
• installed: Prefer installed Python installations, only download managed Python installations if no system Python installation is found
• managed: Prefer managed Python installations over system Python installations, even if fetching is required
• system: Prefer system Python installations over managed Python installations
• only-system: Only use system Python installations; never use managed Python installations

These options allow disabling uv's managed Python versions entirely or always using them and ignoring any existing system installations.

Discovery order

When searching for a Python version, the following locations are checked:

• Managed Python versions in the UV_PYTHON_INSTALL_DIR.
• A Python interpreter on the PATH as python3 on macOS and Linux, or python.exe on Windows.
• On Windows, the Python interpreter returned by py --list-paths that matches the requested version.

If a specific Python version is requested, e.g. --python 3.7, additional executable names are included in the search:

• A Python interpreter on the PATH as, e.g., python3.7 on macOS and Linux.

Python distributions

Python does not publish official distributable CPython binaries, uv uses third-party standalone distributions from the python-build-standalone project. The project is partially maintained by the uv maintainers and is used by many other Python projects.

The Python distributions are self-contained and highly-portable. Additionally, these distributions have various build-time optimizations enabled to ensure they are performant.

These distributions have some behavior quirks, generally as a consequence of portability. See the python-build-standalone quirks documentation for details.

PyPy distributions are provided by the PyPy project.