uv "No interpreter found for Python X" in CI

uv needs a Python interpreter matching your project’s requirement and could not find one on the runner. Either install the version, let uv download it, or point uv at the interpreter you already have.

What this error means

A uv command fails with No interpreter found for Python 3.X in managed installations or search path. The runner has no interpreter satisfying requires-python or the requested --python version.

uv output

error: No interpreter found for Python 3.12 in managed installations or
search path

Common causes

The requested Python is not installed

A minimal runner has no Python 3.12 (or whatever requires-python needs), and uv’s managed installs directory is empty.

uv not allowed to fetch a managed interpreter

With downloads disabled or offline, uv cannot provision the interpreter itself and finds nothing on PATH.

How to fix it

Let uv install the interpreter

uv can download and manage a matching CPython.

Terminal

uv python install 3.12
uv sync   # now finds the interpreter

Or provide Python via the CI action

Set up the interpreter first, then point uv at it.

.github/workflows/ci.yml

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
- run: uv sync --python "$(which python)"

How to prevent it

Use uv python install (or setup-python) so the interpreter exists before uv runs.
Keep requires-python aligned with an interpreter available on the runner.
Allow uv managed downloads, or pre-provision Python on offline runners.