pyenv local: Usage, Options & Common CI Errors

pyenv local pins a Python version for a directory by writing .python-version.

pyenv local selects which installed Python a project uses by writing a .python-version file. In CI it only works if pyenv's shims are on PATH - and the shim/init step is what trips people up.

What it does

pyenv local <version> writes a .python-version file so that python in that directory resolves to the chosen version via pyenv's shims. The shims sit in ~/.pyenv/shims, which must be on PATH (and pyenv init must run) or python falls through to the system interpreter regardless of .python-version.

Common usage

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PYENV_ROOT/shims:$PATH"
eval "$(pyenv init -)"                            # set up shims/rehash
pyenv local 3.12.4
python --version                                  # -> Python 3.12.4
pyenv versions                                     # show installed + active

Common errors in CI

The shim-PATH trap: pyenv local 3.12.4 writes .python-version, but python still runs the system Python because ~/.pyenv/shims is not on PATH and pyenv init was not eval'd - add the shims to PATH and eval "$(pyenv init -)" first. "pyenv: version \"3.12.4\" is not installed" means .python-version names a version you never pyenv install'd. After installing a package with a new console script, run pyenv rehash so its shim appears. Each CI step is a fresh shell, so re-run the init.

Options

Related guides