uv python find

Synopsis

uv python find [OPTIONS] [REQUEST]

Description

Search for a Python installation. Displays the path to the Python executable. See uv help python to view supported request formats and details on discovery behavior.

Arguments

`[REQUEST]`

The Python request. When not provided, the Python requirement of a project in the current directory or parent directories will be used (unless --no-project is specified). See uv help python to view supported request formats. Examples:

3.12 - Find Python 3.12
[email protected] - Find CPython 3.11
>=3.10 - Find Python 3.10 or newer
python3.12 - Find by executable name
/usr/bin/python3 - Find specific installation

Options

Discovery Options

`--no-project`

Avoid discovering a project or workspace. Otherwise, when no request is provided, the Python requirement of a project in the current directory or parent directories will be used. Aliases: --no-workspace

`--system`

Only find system Python interpreters. By default, uv will report the first Python interpreter it would use, including those in an active virtual environment or a virtual environment in the current working directory or any parent directory. The --system option instructs uv to skip virtual environment Python interpreters and restrict its search to the system path.

Environment variable: UV_SYSTEM_PYTHON
Conflicts with: --no-system

`--no-system`

Allow finding Python in virtual environments. This is the default behavior.

Conflicts with: --system

`--script <SCRIPT>`

Find the environment for a Python script, rather than the current project.

Type: Path
Conflicts with: request, --no-project, --system, --no-system

Display Options

`--show-version`

Show the Python version that would be used instead of the path to the interpreter. Example output: 3.12.4 instead of /usr/bin/python3.12

`--resolve-links`

Resolve symlinks in the output path. When enabled, the output path will be canonicalized, resolving any symlinks. Example:

Without flag: /usr/bin/python3 (may be a symlink)
With flag: /usr/lib/python3.12/bin/python3.12 (resolved)

Custom Downloads

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

URL pointing to JSON of custom Python installations.

Type: String

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

Additionally, a specific system Python interpreter can often be requested with:

<executable-path> e.g. /opt/homebrew/bin/python3
<executable-name> e.g. mypython3
<install-dir> e.g. /some/environment/

Discovery Behavior

uv searches for Python in the following order:

Active virtual environment - If a virtual environment is activated
Local virtual environment - .venv in current or parent directories
Project Python requirement - From pyproject.toml or .python-version (unless --no-project)
Managed Python - Python versions installed by uv
System Python - Python found in PATH
Windows registry - On Windows only

With --system, steps 1-2 are skipped.

Output Format

Default (Path)

uv python find 3.12

/Users/user/.local/share/uv/python/cpython-3.12.8-macos-aarch64-none/bin/python3.12

With —show-version

uv python find 3.12 --show-version

3.12.8

With —resolve-links

uv python find --resolve-links

/usr/local/Cellar/[email protected]/3.12.8/Frameworks/Python.framework/Versions/3.12/bin/python3.12

Not Found

uv python find 3.15

error: No Python 3.15 found. Available Python versions:
  3.13.1
  3.12.8
  3.11.11
  3.10.16

Run `uv python install 3.15` to install Python 3.15

Examples

Find default Python

uv python find

Finds the Python version that uv would use in the current directory.

Find specific version

uv python find 3.12

Find with version specifier

uv python find ">=3.10,<3.13"

Finds a Python version matching the specifier.

Find PyPy

uv python find [email protected]

Find system Python only

uv python find --system

Ignores any virtual environments and searches only system-installed Python.

Find and show version

uv python find 3.12 --show-version

Outputs just the version number instead of the full path.

Find with resolved symlinks

uv python find --resolve-links

Shows the actual installation path instead of symlinks.

Find for a specific script

uv python find --script my_script.py

Finds the Python that would be used to run my_script.py, considering inline script metadata.

Verify installation

if uv python find 3.12 > /dev/null 2>&1; then
  echo "Python 3.12 is available"
else
  echo "Python 3.12 not found"
  uv python install 3.12
fi

Use in scripts

# Get the Python path
PYTHON=$(uv python find 3.12)

# Use it directly
$PYTHON -m pip list

# Or get just the version
VERSION=$(uv python find 3.12 --show-version)
echo "Using Python $VERSION"

Check project Python

cd my-project
uv python find

Shows which Python would be used for the project based on .python-version or pyproject.toml.

Find without project influence

uv python find --no-project

Ignores project requirements and finds the default Python.

Find exact executable

uv python find /opt/homebrew/bin/python3

Verifies and returns the path to a specific Python executable.

Use Cases

Verify Python availability

uv python find 3.12 || uv python install 3.12

Install Python 3.12 if it’s not already available.

Get Python for external tools

# Use uv-managed Python with other tools
PYTHON=$(uv python find 3.12)
export PYTHON
make test  # Uses $PYTHON in Makefile

Debug Python resolution

echo "Default Python:"
uv python find

echo "System Python:"
uv python find --system

echo "Python 3.12:"
uv python find 3.12

echo "Project Python:"
cd my-project && uv python find

CI/CD validation

# Verify required Python version exists
if ! uv python find ">=3.11" > /dev/null; then
  echo "Error: Python 3.11+ required"
  exit 1
fi

Compare installations

echo "Virtual env Python:"
uv python find

echo "System Python:"
uv python find --system

echo "Resolved paths:"
uv python find --resolve-links
uv python find --system --resolve-links

Overview

Project Commands

Python Management

Tool Commands

Pip Interface

Build & Publish

Environment

Cache & Maintenance

​Synopsis

​Description

​Arguments

​[REQUEST]

​Options

​Discovery Options

​--no-project

​--system

​--no-system

​--script <SCRIPT>

​Display Options

​--show-version

​--resolve-links

​Custom Downloads

​--python-downloads-json-url <PYTHON_DOWNLOADS_JSON_URL>

​Version Request Formats

​Discovery Behavior

​Output Format

​Default (Path)

​With —show-version

​With —resolve-links

​Not Found

​Examples

​Find default Python

​Find specific version

​Find with version specifier

​Find PyPy

​Find system Python only

​Find and show version

​Find with resolved symlinks

​Find for a specific script

​Verify installation

​Use in scripts

​Check project Python

​Find without project influence

​Find exact executable

​Use Cases

​Verify Python availability

​Get Python for external tools

​Debug Python resolution

​CI/CD validation

​Compare installations

​See Also

Build docs developers (and LLMs) love