Pyenv Commands Cheat Sheet & Reference Guide

August 9, 2025 · 15 min read

Senior Software Engineer & System Architect specializing in Python, Web Systems, Cloud Infrastructure & Automation

Managing multiple Python environments across diverse microservices and backend applications often requires handling competing runtime requirements on a single development machine. In my daily backend engineering workflow, pyenv is an indispensable tool for seamless Python version switching without corrupting system binaries or relying on brittle global setups.

This guide provides a complete technical reference to pyenv subcommands, including CLI flags, attribute options, real-world terminal session examples, and architectural insights into how pyenv resolves environment precedence.

Architecture and Precedence Mechanics

To use pyenv effectively, it helps to understand how it intercepts command calls. Rather than modifying your system python binaries directly, pyenv inserts a directory of shims at the front of your shell's PATH.

When you execute python, pip, or any script installed via a Python package, your shell hits a shim first. The shim analyzes your current environment state and routes the call to the appropriate Python installation.

pyenv evaluates Python version precedence in the following strict order:

PYENV_VERSION Environment Variable: Overrides all other settings for the active shell session (configured via pyenv shell).
Local Directory Specification: Read from a .python-version file in the current working directory or any parent directory traversed upward (configured via pyenv local).
Global User Setting: Read from ~/.pyenv/version (configured via pyenv global).
System Python: The default binary shipped with your operating system path fallback.

Core Command Reference

Like git, pyenv delegates execution to subcommands based on its primary argument. Below is the full command suite detailing options, attributes, and terminal session outputs.

Version Selection Commands

pyenv local

Sets an application-specific Python version by creating or updating a .python-version file in the current working directory.

Flags and Attributes

Flag / Option	Description	Usage Example
`<version> ...`	One or more Python versions to set locally	`pyenv local 3.11.8 3.10.13`
`--unset`	Removes local `.python-version` override in current directory	`pyenv local --unset`
`-f`, `--force`	Force setting versions even if not currently installed	`pyenv local -f 3.12.0`

Terminal Session

$ pyenv local 3.11.8
$ cat .python-version
3.11.8

$ pyenv version
3.11.8 (set by /Users/serhiihrekov/projects/api/.python-version)

Advanced Multi-Version Selection

When specifying multiple versions, the first version serves as primary python while remaining versions are accessible through version-qualified binaries:

$ pyenv local 3.11.8 3.10.13
$ pyenv versions
  system
* 3.11.8 (set by /Users/serhiihrekov/projects/api/.python-version)
* 3.10.13 (set by /Users/serhiihrekov/projects/api/.python-version)

$ python --version
Python 3.11.8

$ python3.10 --version
Python 3.10.13

Backwards Compatibility: Older versions of pyenv stored local settings in .pyenv-version. pyenv still reads .pyenv-version if present, but a .python-version file in the same directory takes precedence.

pyenv global

Sets the default global Python version across all shell sessions by writing to ~/.pyenv/version.

Flags and Attributes

Flag / Option	Description	Usage Example
`<version> ...`	Target version(s) to activate globally across all shells	`pyenv global 3.11.8`
`system`	Special version name targeting OS system Python	`pyenv global system`

Terminal Session

$ pyenv global 3.11.8
$ cat ~/.pyenv/version
3.11.8

$ python --version
Python 3.11.8

Advanced Multi-Version Global Setup

$ pyenv global 3.11.8 3.9.18
$ pyenv versions
  system
  3.8.18
* 3.9.18 (set by /Users/serhiihrekov/.pyenv/version)
* 3.11.8 (set by /Users/serhiihrekov/.pyenv/version)

pyenv shell

Sets an environment-scoped Python version by defining the PYENV_VERSION variable in your current shell session.

Flags and Attributes

Flag / Option	Description	Usage Example
`<version> ...`	Python version(s) to set for current shell session	`pyenv shell 3.12.1`
`--unset`	Unset `PYENV_VERSION` environment variable	`pyenv shell --unset`

Terminal Session

$ pyenv shell 3.12.1
$ echo $PYENV_VERSION
3.12.1

$ pyenv version
3.12.1 (set by PYENV_VERSION environment variable)

$ pyenv shell --unset
$ pyenv version
3.11.8 (set by /Users/serhiihrekov/projects/api/.python-version)

Toolchain and Installation Management

pyenv install

Downloads and compiles Python releases from source using the python-build plugin.

Flags and Attributes

Flag / Option	Description	Usage Example
`-l`, `--list`	List all available installable Python versions and distributions	`pyenv install --list`
`-f`, `--force`	Force compilation and overwrite existing target installation	`pyenv install -f 3.11.8`
`-s`, `--skip-existing`	Skip installation cleanly if target version already exists	`pyenv install -s 3.11.8`
`-k`, `--keep`	Keep source code trees under `$PYENV_BUILD_ROOT`	`pyenv install -k 3.11.8`
`-v`, `--verbose`	Enable verbose compilation logs to `stdout`	`pyenv install -v 3.11.8`
`-p`, `--patch`	Apply patch from `stdin` before compiling	`cat patch.diff \| pyenv install -p 3.11.8`
`-g`, `--debug`	Build a debug binary release	`pyenv install -g 3.11.8`

Terminal Session

$ pyenv install --list | grep "3.11"
3.11.0
...
3.11.8

$ pyenv install 3.11.8
Downloading Python-3.11.8.tar.xz...
-> https://www.python.org/ftp/python/3.11.8/Python-3.11.8.tar.xz
Installing Python-3.11.8...
Installed Python-3.11.8 to /Users/serhiihrekov/.pyenv/versions/3.11.8

Prefix Resolution

$ pyenv install 3.10
Installing Python-3.10.13...
Installed Python-3.10.13 to /Users/serhiihrekov/.pyenv/versions/3.10.13

pyenv uninstall

Removes installed Python distributions from $PYENV_ROOT/versions.

Flags and Attributes

Flag / Option	Description	Usage Example
`<version> ...`	One or more Python versions to uninstall	`pyenv uninstall 3.9.18`
`-f`, `--force`	Force removal without interactive confirmation prompt	`pyenv uninstall -f 3.9.18`

Terminal Session

$ pyenv uninstall 3.9.18
pyenv: remove /Users/serhiihrekov/.pyenv/versions/3.9.18? y

$ pyenv uninstall -f 3.8.18
# Removes 3.8.18 cleanly without prompting

pyenv latest

Resolves and prints the highest installed or known version matching a given prefix.

Flags and Attributes

Flag / Option	Description	Usage Example
`<prefix>`	Version prefix to search (e.g., `3.11` or `3`)	`pyenv latest 3.11`
`-k`, `--known`	Search across all available definitions instead of installed	`pyenv latest -k 3.11`
`-q`, `--quiet`	Suppress error messages on resolution failure	`pyenv latest -q 3.99`

Terminal Session

$ pyenv latest 3.10
3.10.13

$ pyenv latest -k 3.12
3.12.2

Environment Introspection and Executable Routing

pyenv version

Displays the currently active Python version along with the location or setting mechanism that specified it.

Flags and Attributes

Flag / Option	Description	Usage Example
`--bare`	Show only version name without path or environment source	`pyenv version --bare`

Terminal Session

$ pyenv version
3.11.8 (set by /Users/serhiihrekov/projects/api/.python-version)

$ pyenv version --bare
3.11.8

pyenv versions

Lists all Python versions known to pyenv, placing an asterisk (*) next to the active version.

Flags and Attributes

Flag / Option	Description	Usage Example
`--bare`	Show only installed version names without active markers	`pyenv versions --bare`
`--skip-aliases`	Omit version alias symlinks from listed results	`pyenv versions --skip-aliases`

Terminal Session

$ pyenv versions
  system
  3.9.18
  3.10.13
* 3.11.8 (set by /Users/serhiihrekov/projects/api/.python-version)
  3.12.1

pyenv which

Displays the full, absolute file path to the executable binary that pyenv will invoke for a given command.

Flags and Attributes

Flag / Option	Description	Usage Example
`<command>`	Command executable name to locate (e.g. `python`, `pip`)	`pyenv which pytest`
`--nosystem`	Exclude OS system `$PATH` lookups during resolution	`pyenv which --nosystem python`

Terminal Session

$ pyenv which python3
/Users/serhiihrekov/.pyenv/versions/3.11.8/bin/python3

$ pyenv which pytest
/Users/serhiihrekov/.pyenv/versions/3.11.8/bin/pytest

pyenv whence

Lists all installed Python versions that contain a specified binary executable.

Flags and Attributes

Flag / Option	Description	Usage Example
`<command>`	Executable binary name to query across toolchains	`pyenv whence pytest`
`--path`	Output absolute executable paths instead of version strings	`pyenv whence --path pytest`

Terminal Session

$ pyenv whence pytest
3.10.13
3.11.8

$ pyenv whence --path pytest
/Users/serhiihrekov/.pyenv/versions/3.10.13/bin/pytest
/Users/serhiihrekov/.pyenv/versions/3.11.8/bin/pytest

pyenv exec

Executes a command by prepending the active Python version's bin path directly to $PATH, bypassing shim overhead.

Flags and Attributes

Flag / Option	Description	Usage Example
`<command> [args]`	Executable binary and argument list to run directly	`pyenv exec pip install -r reqs.txt`

Terminal Session

$ pyenv exec pip --version
pip 24.0 from /Users/serhiihrekov/.pyenv/versions/3.11.8/lib/python3.11/site-packages/pip (python 3.11)

pyenv root

Displays the absolute path to pyenv's root directory where installed versions, shims, and plugins reside.

Terminal Session

$ pyenv root
/Users/serhiihrekov/.pyenv

pyenv prefix

Displays the installation directory path for one or more Python versions. If no version argument is passed, it outputs the path of the active version.

Flags and Attributes

Flag / Option	Description	Usage Example
`[version]`	Target version to inspect	`pyenv prefix 3.10.13`

Terminal Session

$ pyenv prefix
/Users/serhiihrekov/.pyenv/versions/3.11.8

$ pyenv prefix 3.10.13
/Users/serhiihrekov/.pyenv/versions/3.10.13

pyenv shims

Lists all existing binary shims currently registered under $PYENV_ROOT/shims.

Flags and Attributes

Flag / Option	Description	Usage Example
`--short`	Display only shim executable filenames without full path	`pyenv shims --short`

Terminal Session

$ pyenv shims --short
2to3
idle
pip
pip3
python
python3
pytest

pyenv rehash

Regenerates binary shims for all executables present across installed Python versions ($PYENV_ROOT/versions/*/bin/*).

Terminal Session

$ pyenv rehash

Tip: Run pyenv rehash after installing packages that introduce new command-line executables (such as flit, poetry, or celery) if automatic rehashing is disabled.

pyenv hooks

Lists installed hook scripts registered for a given pyenv command lifecycle.

Flags and Attributes

Flag / Option	Description	Usage Example
`<command>`	Target command lifecycle to inspect hooks for	`pyenv hooks rehash`

Terminal Session

$ pyenv hooks rehash
/Users/serhiihrekov/.pyenv/pyenv.d/rehash/source.bash

Shell Integration and Discovery

pyenv init

Generates the shell integration logic required to configure PATH, inject shims, enable tab completion, and activate pyenv shell.

Flags and Attributes

Flag / Option	Description	Usage Example
`-`	Initialize shims, print `PYENV_SHELL`, setup completion paths	`eval "$(pyenv init -)"`
`--path`	Output shims path setup statements only	`pyenv init --path`
`--no-push-path`	Prevent pushing shims to start of `$PATH` if already present	`pyenv init --no-push-path`
`--no-rehash`	Omit automatic rehash execution from shell startup logic	`pyenv init --no-rehash`

Terminal Session

$ pyenv init -
export PATH="/Users/serhiihrekov/.pyenv/shims:${PATH}"
export PYENV_SHELL=zsh
source '/Users/serhiihrekov/.pyenv/libexec/../completions/pyenv.zsh'

pyenv completions

Lists available shell completions for a given pyenv command.

Flags and Attributes

Flag / Option	Description	Usage Example
`<command> [arg]`	Command and optional arguments to fetch completion targets	`pyenv completions install`

Terminal Session

$ pyenv completions install
--list
--force
--skip-existing
--keep
--verbose
--patch
--debug

pyenv help and pyenv commands

Discovery tools for viewing command documentation and listing registered subcommands.

Terminal Session

$ pyenv commands
commands
completions
exec
global
help
hooks
init
install
latest
local
prefix
rehash
root
shell
shims
uninstall
version
version-file
version-name
version-origin
versions
whence
which

$ pyenv help install
Usage: pyenv install [-f] [-kvp] <version>
       pyenv install [-f] [-kvp] <definition-file>
       pyenv install -l|--list

For official project documentation and installation guides, consult the pyenv GitHub repository.

Architecture and Precedence Mechanics​

Core Command Reference​

Version Selection Commands​

pyenv local​

Flags and Attributes​

Terminal Session​

Advanced Multi-Version Selection​

pyenv global​

Flags and Attributes​

Terminal Session​

Advanced Multi-Version Global Setup​

pyenv shell​

Flags and Attributes​

Terminal Session​

Toolchain and Installation Management​

pyenv install​

Flags and Attributes​

Terminal Session​

Prefix Resolution​

pyenv uninstall​

Flags and Attributes​

Terminal Session​

pyenv latest​

Flags and Attributes​

Terminal Session​

Environment Introspection and Executable Routing​

pyenv version​

Flags and Attributes​

Terminal Session​

pyenv versions​

Flags and Attributes​

Terminal Session​

pyenv which​

Flags and Attributes​

Terminal Session​

pyenv whence​

Flags and Attributes​

Terminal Session​

pyenv exec​

Flags and Attributes​

Terminal Session​

pyenv root​

Terminal Session​

pyenv prefix​

Flags and Attributes​

Terminal Session​

pyenv shims​

Flags and Attributes​

Terminal Session​

pyenv rehash​

Terminal Session​

pyenv hooks​

Flags and Attributes​

Terminal Session​

Shell Integration and Discovery​

pyenv init​

Flags and Attributes​

Terminal Session​

pyenv completions​

Flags and Attributes​

Terminal Session​

pyenv help and pyenv commands​

Terminal Session​

Related articles

Architecture and Precedence Mechanics

Core Command Reference

Version Selection Commands

pyenv local

Flags and Attributes

Terminal Session

Advanced Multi-Version Selection

pyenv global

Flags and Attributes

Terminal Session

Advanced Multi-Version Global Setup

pyenv shell

Flags and Attributes

Terminal Session

Toolchain and Installation Management

pyenv install

Flags and Attributes

Terminal Session

Prefix Resolution

pyenv uninstall

Flags and Attributes

Terminal Session

pyenv latest

Flags and Attributes

Terminal Session

Environment Introspection and Executable Routing

pyenv version

Flags and Attributes

Terminal Session

pyenv versions

Flags and Attributes

Terminal Session

pyenv which

Flags and Attributes

Terminal Session

pyenv whence

Flags and Attributes

Terminal Session

pyenv exec

Flags and Attributes

Terminal Session

pyenv root

Terminal Session

pyenv prefix

Flags and Attributes

Terminal Session

pyenv shims

Flags and Attributes

Terminal Session

pyenv rehash

Terminal Session

pyenv hooks

Flags and Attributes

Terminal Session

Shell Integration and Discovery

pyenv init

Flags and Attributes

Terminal Session

pyenv completions

Flags and Attributes

Terminal Session

pyenv help and pyenv commands

Terminal Session