Pyenv Cheat Sheet

Overview

Pyenv is a Python version management tool that allows you to install, switch between, and manage multiple Python versions on a single machine. It modifies the PATH to intercept Python commands and redirect them to the selected version, without requiring root access or modifying system Python installations.

Pyenv builds Python from source, giving you access to any Python version including CPython, PyPy, Anaconda, Miniconda, Stackless, and Jython. Combined with the pyenv-virtualenv plugin, it provides complete virtual environment management. Pyenv supports per-project Python versions via .python-version files, enabling automatic switching as you navigate between projects.

Installation

# macOS via Homebrew
brew install pyenv

# Linux via pyenv-installer
curl https://pyenv.run | bash

# Manual install (Git)
git clone https://github.com/pyenv/pyenv.git ~/.pyenv

# Install build dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
  libffi-dev liblzma-dev

# Install build dependencies (macOS)
brew install openssl readline sqlite3 xz zlib tcl-tk

# Add to shell profile (~/.bashrc, ~/.zshrc)
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# Install pyenv-virtualenv plugin
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv
eval "$(pyenv virtualenv-init -)"

# Or via Homebrew
brew install pyenv-virtualenv

# Verify
pyenv --version

Core Commands

Command	Description
pyenv install <version>	Install a Python version
pyenv uninstall <version>	Uninstall a version
pyenv versions	List installed versions
pyenv version	Show current active version
pyenv global <version>	Set global default version
pyenv local <version>	Set project-local version
pyenv shell <version>	Set version for current shell
pyenv install --list	List available versions
pyenv rehash	Rehash shims (after installing packages with executables)
pyenv which <command>	Show full path of a command

Installing Python Versions

# List all available versions
pyenv install --list

# List specific versions
pyenv install --list | grep "^  3\."

# Install specific CPython version
pyenv install 3.12.3
pyenv install 3.11.9
pyenv install 3.13.0

# Install with optimizations
PYTHON_CONFIGURE_OPTS="--enable-optimizations" pyenv install 3.12.3

# Install with shared library
PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install 3.12.3

# Install PyPy
pyenv install pypy3.10-7.3.15

# Install Anaconda/Miniconda
pyenv install miniconda3-latest
pyenv install anaconda3-2024.02-1

# Verbose installation (for debugging)
pyenv install -v 3.12.3

Setting Python Versions

# Set global default
pyenv global 3.12.3

# Set multiple (first one is default, others are available)
pyenv global 3.12.3 3.11.9

# Set for current project (creates .python-version file)
cd ~/my-project
pyenv local 3.11.9

# Set for current shell session only
pyenv shell 3.13.0

# Unset shell version
pyenv shell --unset

# Unset local version
pyenv local --unset

# Check current version and why
pyenv version
# 3.12.3 (set by /home/user/.pyenv/version)

# Check all installed versions
pyenv versions
#   system
#   3.11.9
# * 3.12.3 (set by /home/user/.pyenv/version)
#   3.13.0

Virtual Environments (pyenv-virtualenv)

# Create a virtual environment
pyenv virtualenv 3.12.3 my-project-env

# Activate a virtual environment
pyenv activate my-project-env

# Deactivate
pyenv deactivate

# Set as local environment (auto-activates in directory)
cd ~/my-project
pyenv local my-project-env

# List virtual environments
pyenv virtualenvs

# Delete a virtual environment
pyenv virtualenv-delete my-project-env
pyenv uninstall my-project-env

.python-version File

# Create by running
pyenv local 3.12.3

# Or manually
echo "3.12.3" > .python-version

# For virtual environments
echo "my-project-env" > .python-version

# Version auto-switches when entering directory
cd ~/project-a  # Uses 3.12.3
cd ~/project-b  # Uses 3.11.9

Managing Versions

# List installed versions
pyenv versions

# Show where versions are installed
ls $(pyenv root)/versions/

# Show path to specific version
pyenv prefix 3.12.3

# Show path to a command
pyenv which python
pyenv which pip

# Rehash after installing executables
pip install black
pyenv rehash  # Makes 'black' available in PATH

# Uninstall a version
pyenv uninstall 3.10.0

# Update pyenv itself
cd $(pyenv root) && git pull
# Or with Homebrew:
brew upgrade pyenv

Advanced Usage

Custom Build Configuration

# Install with framework support (macOS)
PYTHON_CONFIGURE_OPTS="--enable-framework" pyenv install 3.12.3

# Install with debug symbols
PYTHON_CONFIGURE_OPTS="--with-pydebug" pyenv install 3.12.3-debug

# Custom compilation flags
CFLAGS="-O2 -march=native" pyenv install 3.12.3

# Use specific OpenSSL (macOS)
PYTHON_BUILD_HOMEBREW_OPENSSL_FORMULA=openssl@3 pyenv install 3.12.3

Mirror Configuration

# Use a mirror for faster downloads
export PYTHON_BUILD_MIRROR_URL="https://npm.taobao.org/mirrors/python/"
export PYTHON_BUILD_MIRROR_URL_SKIP_CHECKSUM=1
pyenv install 3.12.3

pyenv with pipx

# Install pipx for global tool management
pyenv global 3.12.3
pip install pipx
pipx ensurepath

# Install CLI tools globally
pipx install black
pipx install poetry
pipx install ruff

Integration with Poetry

# Set Python version for project
pyenv local 3.12.3

# Poetry will use the pyenv-managed Python
poetry env use python
poetry install

Per-Command Version

# Run with specific version without switching
PYENV_VERSION=3.11.9 python --version
PYENV_VERSION=3.11.9 pip install requests

Configuration

# Environment variables
export PYENV_ROOT="$HOME/.pyenv"          # pyenv installation directory
export PYENV_VERSION="3.12.3"             # Override active version
export PYENV_VIRTUALENV_DISABLE_PROMPT=1  # Don't modify shell prompt
export PYTHON_BUILD_CACHE_PATH="$PYENV_ROOT/cache"  # Cache downloads

# Shell initialization (~/.zshrc or ~/.bashrc)
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"  # If using pyenv-virtualenv

Troubleshooting

Issue	Solution
BUILD FAILED	Install build dependencies; check pyenv install -v output
python: command not found	Ensure pyenv init is in shell profile; restart shell
SSL errors during install	Install/update OpenSSL development headers
sqlite3 module missing	Install libsqlite3-dev before building Python
Slow shell startup	Use pyenv init - --no-rehash for lazy initialization
shims not updating	Run pyenv rehash after installing packages with binaries
Version not switching	Check .python-version file; verify pyenv init is loaded
Virtualenv not auto-activating	Ensure eval "$(pyenv virtualenv-init -)" is in shell profile