pyenv "version `X` is not installed" / "version not found" in CI

pyenv was asked for a Python version it has not installed, or its shims are not on PATH. The .python-version file or a pyenv local setting names a version the runner never built.

What this error means

A command fails with pyenv: version 3.12.2' is not installed (set by /repo/.python-version) or pyenv: python: command not found`. pyenv exists, but the requested interpreter is missing or the shims are not initialized.

pyenv output

pyenv: version `3.12.2' is not installed (set by /home/runner/work/repo/.python-version)
# or
pyenv: python: command not found

Common causes

Requested version not installed

A committed .python-version (or pyenv local) names a version no one ran pyenv install for on this runner, so pyenv cannot select it.

pyenv not initialized in the shell

Without pyenv init and the shims directory on PATH, pyenv’s python shim is not found and commands fall through or error.

How to fix it

Install the exact version pyenv expects

Terminal

pyenv install -s "$(cat .python-version)"
pyenv versions

Initialize pyenv on PATH

Make sure shims are active so the selected interpreter resolves.

Terminal

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
python --version

Or use the CI action instead of pyenv

On hosted CI, actions/setup-python is usually simpler and avoids building interpreters at job time.

.github/workflows/ci.yml

- uses: actions/setup-python@v5
  with:
    python-version-file: .python-version

How to prevent it

Keep .python-version in sync with versions actually installed in CI.
Initialize pyenv (shims on PATH) before any python command.
On hosted runners, prefer actions/setup-python over building via pyenv.