> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# uv python find

> Search for a Python installation

## Synopsis

```bash theme={null}
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)

```bash theme={null}
uv python find 3.12
```

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

### With --show-version

```bash theme={null}
uv python find 3.12 --show-version
```

```
3.12.8
```

### With --resolve-links

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
uv python find
```

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

### Find specific version

```bash theme={null}
uv python find 3.12
```

### Find with version specifier

```bash theme={null}
uv python find ">=3.10,<3.13"
```

Finds a Python version matching the specifier.

### Find PyPy

```bash theme={null}
uv python find pypy@3.10
```

### Find system Python only

```bash theme={null}
uv python find --system
```

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

### Find and show version

```bash theme={null}
uv python find 3.12 --show-version
```

Outputs just the version number instead of the full path.

### Find with resolved symlinks

```bash theme={null}
uv python find --resolve-links
```

Shows the actual installation path instead of symlinks.

### Find for a specific script

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
uv python find --no-project
```

Ignores project requirements and finds the default Python.

### Find exact executable

```bash theme={null}
uv python find /opt/homebrew/bin/python3
```

Verifies and returns the path to a specific Python executable.

## Use Cases

### Verify Python availability

```bash theme={null}
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

```bash theme={null}
# Use uv-managed Python with other tools
PYTHON=$(uv python find 3.12)
export PYTHON
make test  # Uses $PYTHON in Makefile
```

### Debug Python resolution

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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`](python-install.mdx) - Download and install Python versions
* [`uv python list`](python-list.mdx) - List available Python installations
* [`uv python pin`](python-pin.mdx) - Pin to a specific Python version
* [`uv python uninstall`](python-uninstall.mdx) - Uninstall Python versions