pyenv install: Usage, Options & Common CI Errors

pyenv install compiles and installs a specific Python version from source.

pyenv installs Python versions by compiling from source, so it needs build dependencies present. The common CI failure is a BUILD FAILED caused by missing development headers (libssl, zlib, etc.).

What it does

pyenv install <version> downloads the CPython source and compiles it into ~/.pyenv/versions. Because it builds from source, the runner must have a C toolchain and several -dev libraries; otherwise the build succeeds but silently lacks modules (no ssl, no sqlite3) or fails outright.

Common usage

Terminal

# Debian build deps first:
apt-get install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev libffi-dev liblzma-dev
pyenv install 3.12.4
pyenv install --list | grep 3.12        # available versions
pyenv install -s 3.12.4                  # skip if already installed

Common errors in CI

"BUILD FAILED (... using python-build ...)" with "The Python ... ssl extension was not compiled" means libssl-dev is missing; "ModuleNotFoundError: No module named \"_sqlite3\"" at runtime means libsqlite3-dev was absent at build time. Install the full -dev set (above) before pyenv install. "version X is already installed" needs -s/--skip-existing or --force. Builds are slow - cache ~/.pyenv/versions in CI. zlib not available also fails the build immediately.

Options

Flag	What it does
--list	List installable versions
-s / --skip-existing	Do nothing if already installed
-f / --force	Reinstall even if present
-v / --verbose	Show the full build log
-k / --keep	Keep the source tree after building