pyenv Cheat Sheet (Mac & Linux)

Table of contents

1. What is pyenv?
2. Installation
   1. Prerequisites
   2. Install pyenv
      1. Using Homebrew (MacOS/Linux)
      2. Manual (Universal)
   3. Shell Configuration
3. Install Python Versions
   1. List available versions
   2. Install a version
   3. Uninstall a version
4. pyenv Usage
   1. Show current Python version
   2. List all installed versions
   3. Set global Python version
   4. Set local Python version (for project dir)
   5. Set a virtual env inside the project (using Python’s venv)
   6. Set shell-specific version
5. pyenv-virtualenv (manage virtual environments)
   1. Install:
   2. Add to shell config:
   3. Usage:
6. Upgrading Python in an Existing Project
7. Troubleshooting
   1. pyenv not found?
   2. Build failed?
8. Common Paths
9. Cleanup
   1. Remove pyenv
10. Tips

---

What is pyenv?

pyenv is a tool that lets you easily switch between multiple versions of Python. It works by manipulating the PATH to point to the desired Python version.

---

Installation

Prerequisites

MacOS:

brew update
brew install openssl readline sqlite3 xz zlib

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install -y make build-essential libssl-dev \
libreadline-dev zlib1g-dev libsqlite3-dev curl git

---

Install pyenv

Using Homebrew (MacOS/Linux)

brew install pyenv

Manual (Universal)

curl https://pyenv.run | bash

---

Shell Configuration

Add to your shell config (~/.bashrc, ~/.zshrc, etc.):

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

Then restart your shell:

exec "$SHELL"

---

Install Python Versions

List available versions

pyenv install --list
pyenv install --list | grep -E ' 3\.([1-9][0-9]+)'

Install a version

pyenv install 3.11.9

Uninstall a version

pyenv uninstall 3.11.9

---

pyenv Usage

Show current Python version

pyenv version
ls $PYENV_ROOT/versions/

List all installed versions

pyenv versions

Set global Python version

pyenv global 3.11.9

Set local Python version (for project dir)

pyenv local 3.10.12

Creates a .python-version file in current directory.

Set a virtual env inside the project (using Python’s venv)

python -m venv .env

Create .env/ folder inside the project

Set shell-specific version

pyenv shell 3.8.18

---

pyenv-virtualenv (manage virtual environments)

Install:

brew install pyenv-virtualenv

Add to shell config:

eval "$(pyenv virtualenv-init -)"

Usage:

• Create virtualenv:

pyenv virtualenv 3.10.6 myenv

• Activate virtualenv:

pyenv activate myenv

• Deactivate:

pyenv deactivate

• Auto-activate per-project:

echo "myenv" > .python-version

• Set the local environment using pyenv local

pyenv local my-awesome-env

• List pyenv virtualenvs

pyenv virtualenvs

• Delete the Virtual Environment

pyenv uninstall <env-name>

---

Upgrading Python in an Existing Project

If a project needs a new Python version:

pyenv install 3.13.0
pyenv virtualenv 3.13.0 newenv
pyenv local newenv
pip install -r requirements.txt

---

Troubleshooting

pyenv not found?

Check if installed and shell configured properly.

command -v pyenv

Should return something like /home/youruser/.pyenv/bin/pyenv

Build failed?

Install missing dependencies. Check for errors related to:

• zlib
• openssl
• readline

---

Common Paths

• Pyenv root: ~/.pyenv
• Installed Python: ~/.pyenv/versions/
• Virtualenvs: ~/.pyenv/versions/<env-name>

---

Cleanup

Remove pyenv

rm -rf ~/.pyenv

Also remove lines from your shell config file.

---

Tips

• Use pyenv local in each project.
• Combine with pipx or poetry for isolated environments.
• For global Python packages per version: use ~/.pyenv/versions/3.x.y/lib/python3.x/site-packages/

---