uv python find

Search for a Python installation

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
• cpython@3.11 - 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. 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

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:

1. Active virtual environment - If a virtual environment is activated
2. Local virtual environment - .venv in current or parent directories
3. Project Python requirement - From pyproject.toml or .python-version (unless --no-project)
4. Managed Python - Python versions installed by uv
5. System Python - Python found in PATH
6. 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/python@3.12/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 pypy@3.10

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

See Also

• uv python install - Download and install Python versions
• uv python list - List available Python installations
• uv python pin - Pin to a specific Python version
• uv python uninstall - Uninstall Python versions