pyenv Administrator & Developer Guide

This guide is the operational and architectural reference for pyenv — the shell-based Python version manager. It is written for the people who deploy pyenv across machines and CI, harden and tune Python builds, automate provisioning, write plugins, or need to understand exactly what every line of pyenv init does to a shell.

For installation and day-to-day command usage, see the companion User Guide. This document goes deeper: the shim execution model, the hook system, the version-resolution pipeline, the complete build-customization surface, security considerations, and the project's internal structure.

Table of Contents

• Executive Summary
• Architecture
  • The dispatcher model
  • The shim mechanism
  • The rehash pipeline
  • The hook system
  • Shell integration internals
  • Version resolution pipeline
• Repository Structure
• System Requirements
• Filesystem Layout
• Configuration Reference
  • Runtime environment variables
  • Build customization (python-build)
• Deployment & Provisioning
• Operations
• Security
• Writing Plugins
• Build System & Testing
• Troubleshooting (Operational)
• Potential Improvements
• Quick Reference

Executive Summary

pyenv is a Python interpreter version manager implemented entirely as POSIX shell scripts. It has no compiled core (aside from one optional Bash builtin for speed) and no runtime dependency on Python itself — a deliberate design choice that avoids any bootstrap problem.

Its central mechanism is the shim: a directory of lightweight executables placed at the front of PATH that intercept invocations of python, pip, and every command provided by an installed Python, then redirect them to the version selected by configuration. Selection is layered — shell session, project directory, then global user default — and resolved fresh on every command.

Note

Because pyenv is "pure shell," its attack surface, performance profile, and failure modes are those of shell scripts and the build toolchain — not of a long-running daemon. There is no service to monitor, no port to open, and no privileged process.

Architecture

The dispatcher model

pyenv is a thin front-end (libexec/pyenv) that delegates to subcommands by name, exactly like git. When you run pyenv install, the dispatcher locates an executable named pyenv-install on PATH and execs it.

The dispatcher's startup sequence (libexec/pyenv):

1. Handle --debug by exporting PYENV_DEBUG=1 and enabling set -x with an informative PS4.
2. Resolve its own install prefix via a realpath/readlink abs_dirname (preferring the optional realpath Bash builtin in src/ when present, else GNU readlink).
3. Normalize PYENV_ROOT (default ~/.pyenv) and PYENV_DIR (default $PWD).
4. Prepend every plugins/*/bin directory and libexec to PATH so subcommands and plugin commands are discoverable.
5. Build PYENV_HOOK_PATH from a fixed set of locations plus per-plugin etc/pyenv.d directories.
6. Dispatch on the first argument: empty prints version+help, -v/--version runs pyenv---version, -h/--help runs pyenv-help, otherwise exec pyenv-<command> with the remaining args (a trailing --help is rerouted to pyenv-help <command>).

pyenv install 3.12.4
  │
  ├─ libexec/pyenv               (dispatcher: sets PYENV_ROOT/PATH/HOOK_PATH)
  └─ exec pyenv-install 3.12.4   (resolved from plugins/python-build/bin)
        └─ python-build …        (downloads, configures, compiles, installs)

Each subcommand is a standalone script carrying a # Summary: and # Usage: header comment (surfaced by pyenv help) and a --complete branch that prints its valid completions/flags (consumed by the shell completion scripts).

The shim mechanism

The shim is the heart of pyenv. After pyenv init places $(pyenv root)/shims at the front of PATH, every Python-provided command name in that directory shadows the real one.

A shim is a copy of this prototype shim (generated by pyenv-rehash):

#!/usr/bin/env bash
set -e
[ -n "$PYENV_DEBUG" ] && set -x

program="${0##*/}"

export PYENV_ROOT="…"
SHIM_PATH=${0%/*}
if [[ $SHIM_PATH != "$PYENV_ROOT/shims" ]]; then
  export _PYENV_SHIM_PATH="$SHIM_PATH"
fi
exec "$(command -v pyenv)" exec "$program" "$@"

Every shim is byte-for-byte identical except for its filename. When invoked, the shim simply re-execs pyenv exec <its-own-name> <args>. pyenv exec then resolves the active version, prepends that version's bin/ to PATH, sets PYENV_VERSION, and runs the real executable.

Important

Because shims are identical copies, pyenv detects an upgrade by comparing the first existing shim against the freshly generated prototype. If they differ, all shims are deleted and regenerated. This is why a pyenv upgrade transparently refreshes the shim directory on the next rehash.

The rehash pipeline

pyenv-rehash regenerates the shim directory to match the set of executables across all installed versions. Its design handles concurrency and partial failures carefully:

1. Locking. It uses the shell's noclobber option to atomically create $(pyenv root)/shims/.pyenv-shim as a lock. Only one rehash runs at a time. A lock file older than 10 minutes is treated as stale and removed. The wait loop honors PYENV_REHASH_TIMEOUT (default 60s).
2. Writability probe. Because the Linux Landlock sandbox can make [ -w ] lie (kernel ≥ 6.14.0), rehash also probes writability by attempting a real mktemp inside the shims directory.
3. Prototype creation. It writes the prototype shim shown above.
4. Upgrade detection. remove_outdated_shims wipes the directory if the existing shims differ from the new prototype.
5. Registration. make_shims $(pyenv-versions --executables) registers a shim name for every executable in every installed version. Bash ≥ 4 uses an associative array; Bash 3 falls back to a space-delimited string.
6. Plugin hooks. Every script returned by pyenv-hooks rehash is sourced, letting plugins register or suppress shims (see The hook system).
7. Install & prune. Registered shims are created (hard-link-style copies of the prototype), then any unregistered file in the directory is removed.

Note

The bundled pyenv.d/rehash/conda.bash hook overrides make_shims to skip creating shims for Anaconda-provided system binaries (e.g. openssl, curl) so they don't shadow the user's real tools. pyenv.d/rehash/source.bash rewrites selected shims so that sourced scripts (rather than executed binaries) work correctly.

The hook system

Hooks are the official extension point. The dispatcher assembles PYENV_HOOK_PATH at startup from, in order:

1. Any pre-existing PYENV_HOOK_PATH value.
2. $(pyenv root)/pyenv.d.
3. pyenv's own bundled pyenv.d (unless pyenv was cloned directly into PYENV_ROOT).
4. System paths: /usr/etc/pyenv.d, /usr/local/etc/pyenv.d, /etc/pyenv.d, /usr/lib/pyenv/hooks.
5. Each $(pyenv root)/plugins/*/etc/pyenv.d.

A hook is a .bash file under <hook-path>/<command>/. When a command runs pyenv-hooks <command>, it collects every matching hook script; the command then sources them at a defined point. The bundled hook directories are:

Tip

Use pyenv hooks <command> to enumerate exactly which hook scripts are active for a command on a given machine — invaluable when a plugin changes behavior unexpectedly.

Shell integration internals

pyenv init - is the only pyenv command that injects code into your interactive shell. Running eval "$(pyenv init - <shell>)" performs these steps (see libexec/pyenv-init):

1. Detect shell (skipped if you pass the shell name — recommended for speed). Detection reads /proc/$PPID/cmdline or ps to identify the parent shell.
2. Create dirs — mkdir -p $(pyenv root)/{shims,versions}.
3. Set up the shims path — prepend $(pyenv root)/shims to PATH, first stripping any existing occurrence so repeated init calls don't duplicate entries. --no-push-path guards this with a "skip if already present" check instead.
4. Export PYENV_SHELL so subcommands know the active shell.
5. Source completions for the detected shell from completions/pyenv.<shell> if readable.
6. Emit a rehash (command pyenv rehash) unless --no-rehash is given.
7. Define the pyenv shell function, which intercepts the state-mutating subcommands (those returned by pyenv commands --sh, e.g. shell, rehash) and evals their output in the current shell, delegating everything else to the real pyenv binary.

eval "$(pyenv init - bash)"      → full integration (shims + function + completion + rehash)
eval "$(pyenv init --path)"      → shims path + rehash only, no shell function/completion
pyenv init --install [shell]     → append the setup lines to the shell's startup files
pyenv init --detect-shell        → print detected shell + profile/rc file paths

Important

The shell function is what makes pyenv shell, which must mutate the calling shell's PYENV_VERSION, possible. Without integration, only the non-mutating subcommands work; pyenv emits shell integration not enabled for pyenv shell.

pyenv init --install writes to per-shell startup files. For POSIX shells it targets both the rc file (interactive) and the login profile (~/.bash_profile if present else ~/.profile for Bash; ~/.zprofile for Zsh). It refuses to edit any file that already contains the string pyenv (case-insensitive), printing guidance to apply changes manually — a guard against duplicate or conflicting configuration.

Version resolution pipeline

On each shim invocation, pyenv exec (through pyenv-version-name/pyenv-version-file) determines the active version from the first source that resolves:

1. $PYENV_VERSION                         (set by `pyenv shell`)
2. ./.python-version                      (current directory)
3. ../.python-version, ../../…            (walk up to filesystem root)
4. $(pyenv root)/version                  (global; absent ⇒ "system")

Multiple whitespace/newline-separated versions in any source are all activated, searched left-to-right; system is always implicitly appended last (fall-through). Prefix auto-resolution applies to all subcommands except uninstall: install resolves a prefix to the latest known version, other commands to the latest installed one. A legacy .pyenv-version file is still honored but a sibling .python-version takes precedence.

Repository Structure

pyenv/
├── bin/                     Thin entry stubs (e.g. `pyenv` on PATH)
├── libexec/                 Core subcommands — one script per `pyenv-<cmd>`
│   ├── pyenv                Dispatcher
│   ├── pyenv-init           Shell integration generator
│   ├── pyenv-rehash         Shim regeneration
│   ├── pyenv-exec           Run a command under the selected version
│   ├── pyenv-version*       Resolution + reporting commands
│   ├── pyenv-global/-local  Selection persistence
│   ├── pyenv-sh-shell       Session selection (shell-function backed)
│   └── …                    which, whence, prefix, root, latest, hooks, shims, commands, completions, help
├── plugins/
│   └── python-build/        The build engine behind `pyenv install`
│       ├── bin/             pyenv-install, pyenv-uninstall, python-build
│       ├── share/python-build/   Build definitions (one file per version) + patches
│       └── scripts/         Maintenance helpers (add_cpython.py, add_miniconda.py, …)
├── pyenv.d/                 Bundled hooks (exec/, rehash/, install/)
├── completions/             pyenv.bash, pyenv.zsh, pyenv.fish, pyenv.pwsh
├── man/man1/pyenv.1         Man page
├── src/                     Optional C `realpath` Bash builtin (speed-up)
├── test/                    Bats test suite + Dockerfile
├── COMMANDS.md              Command reference
├── CHANGELOG.md             Release history
└── README.md                Primary documentation

Note

The bulk of the 1,500+ files in the repo are build definitions and patches under plugins/python-build/share/python-build/. Each installable Python version is a small shell definition file; per-version patches live in patches/<version>/. The executable surface — the part that does the work — is the ~25 scripts in libexec/ plus python-build.

System Requirements

Filesystem Layout

Everything pyenv manages lives under the pyenv root (PYENV_ROOT, default ~/.pyenv):

Tip

Because version names are just directory names, you can rename or symlink versions, or back up versions/ directly. A version "exists" to pyenv if and only if its directory is present.

Configuration Reference

Runtime environment variables

These influence pyenv's behavior at command time.

Build customization (python-build)

These variables tune pyenv install / python-build. They are the primary lever for hardening, optimizing, mirroring, and offline-provisioning Python builds.

Build locations & caching

Download & mirrors

Dependency ecosystems (macOS/BSD)

Compiler & make

Note

Default build behavior aims for least surprise but sets a few non-default options: --enable-shared is on (required to embed CPython and matches the official Docker image), --with-universal-archs defaults to universal2 on Apple Silicon, and MACOSX_DEPLOYMENT_TARGET defaults to the running macOS version. Pass overrides via CONFIGURE_OPTS/PYTHON_CONFIGURE_OPTS.

Deployment & Provisioning

Reproducible install on a fleet of machines

Pin pyenv to an exact tag and a known PYENV_ROOT:

export PYENV_ROOT=/opt/pyenv
git clone --branch v2.7.1 --depth 1 https://github.com/pyenv/pyenv.git "$PYENV_ROOT"

Then provision shells non-interactively. For automation that must not edit dotfiles, prefer --path and avoid the interactive --install:

export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"

Docker / CI

The recommended pattern is to pin a version at build time and put shims on PATH:

ENV PYENV_ROOT=/opt/pyenv
ENV PATH=$PYENV_ROOT/shims:$PYENV_ROOT/bin:$PATH
RUN git clone --branch v2.7.1 --depth 1 https://github.com/pyenv/pyenv.git $PYENV_ROOT \
 && pyenv install 3.12.4 \
 && pyenv global 3.12.4 \
 && pyenv rehash

Tip

For CI agents that need to switch Python mid-job, point BASH_ENV at a file that runs eval "$(pyenv init - bash)" so each step gets shims. Mind the BASH_ENV/.bashrc loop warning when doing so.

Offline / air-gapped builds

1. Pre-seed PYTHON_BUILD_CACHE_PATH (e.g. mkdir -p $PYENV_ROOT/cache) and copy source archives there under the filename pyenv reports in its "Downloading …" message.
2. Or stand up an internal mirror and set PYTHON_BUILD_MIRROR_URL (with PYTHON_BUILD_MIRROR_URL_SKIP_CHECKSUM for pull-through caches).

Operations

Health checks

# Confirm shims are first on PATH
echo "$PATH" | tr ':' '\n' | grep -n shims

# Confirm a selected version resolves correctly
pyenv which python

# Confirm a freshly pip-installed tool got a shim
pip install pytest && pyenv rehash && pyenv which pytest

Security

pyenv has no network service and runs with the user's own privileges. The meaningful security considerations are around how Python is obtained and built.

Caution

Curl-to-shell installation. curl -fsSL https://pyenv.run | bash executes a remote script. For controlled environments, prefer a pinned git checkout (--branch <tag>) or vendor the installer and review it, rather than piping a live URL into a shell.

Writing Plugins

A pyenv plugin is a directory under $(pyenv root)/plugins/<name>/ that mirrors pyenv's own layout. The mapping is simple: anything pyenv looks for under $(pyenv root)/<path> it also looks for under $(pyenv root)/plugins/<name>/<path>.

Authoring a subcommand. Make bin/pyenv-foo executable, add a # Summary:/# Usage: header so pyenv help foo works, and handle a --complete first argument to feed shell completion.

Authoring a hook. A hook is a Bash fragment sourced by the host command — it shares the command's variables and functions and can override them (as conda.bash overrides make_shims). To affect shell state from a hook, it must run within a sh-* command path that the shell function evals.

See Authoring plugins on the wiki for the full hook-point catalog.

Build System & Testing

pyenv's test suite uses Bats, driven by a Makefile.

Filter tests with Bats environment variables:

BATS_TEST_FILTER=".*installed.*" BATS_FILE_FILTER="build.bats" make test-plugin

build.bats
 ✓ yaml is installed for python
 ✓ homebrew is used in Linux if Pyenv is installed with Homebrew
 ✓ homebrew is not used in Linux if Pyenv is not installed with Homebrew

3 tests, 0 failures

Run the raw suite directly with Bats:

bats test
bats test/<file>.bats

Note

The optional src/ C extension provides a realpath Bash builtin. Build it with src/configure && make -C src; it is a pure performance optimization and pyenv falls back to GNU readlink if it is absent. Tests run across multiple Bash versions (including 3.2) because pyenv deliberately supports old Bash.

Troubleshooting (Operational)

Symptom: rehash intermittently fails to acquire its lock

Cause: A crashed rehash left .pyenv-shim, or storage is slow. (#3457) Diagnosis: ls -la $(pyenv root)/shims/.pyenv-shim; check its age. Resolution: Stale locks older than 10 minutes are auto-removed; force with rm -f $(pyenv root)/shims/.pyenv-shim. Raise PYENV_REHASH_TIMEOUT on slow filesystems. Keep shims on local storage.

Symptom: shims dir reports unwritable on a sandboxed host

Cause: Landlock (Linux ≥ 6.14.0) can make [ -w ] report incorrectly. pyenv compensates with a mktemp probe, but a genuinely read-only shims/ still fails. Resolution: Ensure the user owns and can write $(pyenv root)/shims; review Landlock/AppArmor policy for the directory.

Symptom: build fails with a missing-module error after a successful compile

Cause: A development header (OpenSSL, SQLite, expat, libffi) was absent at build time, so CPython built without that module. (#3449) Resolution: Install the dev package, then pyenv install -f <version>. Unset a misleading LD_LIBRARY_PATH. Consult Common build problems.

Symptom: pyenv init causes an infinite loop or slow shells

Cause: BASH_ENV pointing at .bashrc (#264), or repeated detection/rehash at startup (#2918). Resolution: Put eval "$(pyenv init - bash)" in .bash_profile, not .bashrc, on such systems. Always name the shell, and add --no-rehash to the init line, rehashing manually after installs.

Potential Improvements

Drawn from the project's own open issue tracker, these are areas an operator or contributor may want to track or address:

• Prebuilt CPython distribution (#2334) — would eliminate the build-toolchain requirement for common platforms; today every source release compiles locally.
• XDG base-directory compliance (#1789) — PYENV_ROOT currently centralizes config+data+cache under one tree rather than following $XDG_CONFIG_HOME/$XDG_CACHE_HOME.
• Shim startup latency (#2802, #2375) — each shim invocation re-execs pyenv; a hot-path optimization would reduce per-command overhead, especially on macOS.
• Signature verification of CPython artifacts (#3087) — current verification is SHA-2 checksum based; Sigstore verification would strengthen supply-chain assurance.
• Sandbox/Landlock writability detection — the mktemp probe is a workaround for a kernel access() quirk; a cleaner errno-aware check would be more robust.

Note

These reflect open community requests at the documented commit and are not commitments by the project. Verify current status on the issue tracker before relying on any of them.

Quick Reference

Selection precedence (highest first): PYENV_VERSION → ./.python-version → parent .python-version → $(pyenv root)/version → system.

Init modes: pyenv init - (full) · pyenv init --path (shims only) · pyenv init --install (edit dotfiles) · pyenv init --detect-shell.

Key paths: versions $(pyenv root)/versions/<name>/ · shims $(pyenv root)/shims/ · global file $(pyenv root)/version · cache $(pyenv root)/cache/.

Most-used commands:

Build tuning quick hits: PYTHON_CONFIGURE_OPTS='--enable-optimizations --with-lto' for speed · PYTHON_BUILD_CACHE_PATH for caching · PYTHON_BUILD_MIRROR_URL for an internal mirror · CONFIGURE_OPTS/CC/MAKE_OPTS for toolchain control.