$ uv python find --system
When searching for a Python version, the following locations are checked:
Managed Python installations in the UV_PYTHON_INSTALL_DIR.
A Python interpreter on the PATH as python, python3, or python3.x on macOS and Linux, or
python.exe on Windows.
On Windows, the Python interpreters in the Windows registry and Microsoft Store Python
interpreters (see py --list-paths) that match the requested version.
In some cases, uv allows using a Python version from a virtual environment. In this case, the
virtual environment's interpreter will be checked for compatibility with the request before
searching for an installation as described above. See the
pip-compatible virtual environment discovery
documentation for details.
When performing discovery, non-executable files will be ignored. Each discovered executable is
queried for metadata to ensure it meets the requested Python version. If
the query fails, the executable will be skipped. If the executable satisfies the request, it is used
without inspecting additional executables.
When searching for a managed Python version, uv will prefer newer versions first. When searching for
a system Python version, uv will use the first compatible version — not the newest version.
If a Python version cannot be found on the system, uv will check for a compatible managed Python
version download.
Python pre-releases will not be selected by default. Python pre-releases will be used if there is no
other available installation matching the request. For example, if only a pre-release version is
available it will be used but otherwise a stable release version will be used. Similarly, if the
path to a pre-release Python executable is provided then no other Python version matches the request
and the pre-release version will be used.
If a pre-release Python version is available and matches the request, uv will not download a stable
Python version instead.
By default, uv will automatically download Python versions when needed.
The python-downloads option can be used to disable
this behavior. By default, it is set to automatic; set to manual to only allow Python downloads
during uv python install.
The python-downloads setting can be set in a
persistent configuration file to change the default behavior, or
the --no-python-downloads flag can be passed to any uv command.
By default, uv will attempt to use Python versions found on the system and only download managed
interpreters when necessary.
The python-preference option can be used to adjust
this behavior. By default, it is set to managed which prefers managed Python installations over
system Python installations. However, system Python installations are still preferred over
downloading a managed Python version.
The following alternative options are available:
only-managed: Only use managed Python installations; never use system Python installations
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.
Automatic Python version downloads can be disabled
without changing the preference.
uv supports the CPython, PyPy, and GraalPy Python implementations. If a Python implementation is not
supported, uv will fail to discover its interpreter.
The implementations may be requested with either the long or short name:
CPython: cpython, cp
PyPy: pypy, pp
GraalPy: graalpy, gp
Implementation name requests are not case sensitive.
See the Python version request documentation for more details on the
supported formats.
uv supports downloading and installing CPython and PyPy distributions.
As Python does not publish official distributable CPython binaries, uv instead uses pre-built
distributions from the Astral
python-build-standalone project.
python-build-standalone is also is used in many other Python projects, like
Rye, Mise, and
bazelbuild/rules_python.
The uv Python distributions are self-contained, highly-portable, and performant. While Python can be
built from source, as in tools like pyenv, doing so requires preinstalled system dependencies, and
creating optimized, performant builds (e.g., with PGO and LTO enabled) is very slow.
These distributions have some behavior quirks, generally as a consequence of portability; and, at
present, uv does not support installing them on musl-based Linux distributions, like Alpine Linux.
See the
python-build-standalone quirks
documentation for details.
PyPy distributions are provided by the PyPy project.
