# The Ultimate Pyenv Cheatsheet

A comprehensive quick reference guide for `pyenv`, the simple Python version manager. This cheatsheet is designed for both beginners and advanced users, covering everything from basic Python version management to advanced workflows and plugin usage.

**Author:** MiniMax Agent**Date:** 2025-11-19

## 1. Quick Start

Get up and running with `pyenv` in minutes.

| Task                         | Command                                      | Notes                                                    |                                                          |
| :--------------------------- | :------------------------------------------- | :------------------------------------------------------- | :------------------------------------------------------- |
| **Install** `pyenv`          | `curl [https://pyenv.run](https://pyenv.run) | bash`                                                    | One-line installer for Unix-based systems (macOS/Linux). |
| **List available versions**  | `pyenv install --list`                       | Shows all Python versions available for installation.    |                                                          |
| **Install a Python version** | `pyenv install 3.12.0`                       | Installs Python 3.12.0 on your system.                   |                                                          |
| **List installed versions**  | `pyenv versions`                             | Shows all Python versions currently installed via pyenv. |                                                          |
| **Set global version**       | `pyenv global 3.12.0`                        | Sets Python 3.12.0 as the default for all shells.        |                                                          |
| **Set local version**        | `pyenv local 3.12.0`                         | Creates `.python-version` file for current directory.    |                                                          |
| **Set shell version**        | `pyenv shell 3.12.0`                         | Sets Python 3.12.0 for current shell session only.       |                                                          |
| **Check current version**    | `pyenv version`                              | Shows the Python version currently active.               |                                                          |

---

## 2. Installation Guide

`pyenv` supports macOS, Linux, and Windows (via WSL or pyenv-win).

| OS          | Method                           | Command                                                 | Notes                                             |                                     |
| :---------- | :------------------------------- | :------------------------------------------------------ | :------------------------------------------------ | :---------------------------------- |
| **macOS**   | Official Installer (Recommended) | `curl [https://pyenv.run](https://pyenv.run)            | bash`                                             | Includes pyenv and popular plugins. |
|             | Homebrew                         | `brew install pyenv`                                    | Requires manual shell configuration.              |                                     |
|             | Git Manual                       | `git clone https://github.com/pyenv/pyenv.git ~/.pyenv` | Manual installation, full control.                |                                     |
| **Linux**   | Official Installer (Recommended) | `curl [https://pyenv.run](https://pyenv.run)            | bash`                                             | Works on most Linux distributions.  |
|             | Git Manual                       | `git clone https://github.com/pyenv/pyenv.git ~/.pyenv` | For users who prefer manual setup.                |                                     |
| **Windows** | WSL (Recommended)                | Use Linux installation in WSL                           | Full pyenv functionality in WSL environment.      |                                     |
|             | pyenv-win                        | `choco install pyenv-win`                               | Native Windows version with limited functionality |                                     |
| **Any OS**  | pip                              | `pip install pyenv-win`                                 | Only for Windows pyenv-win.                       |                                     |

### Shell Configuration

Add these lines to your shell configuration file (`.bashrc`, `.zshrc`, `.bash_profile`, etc.):

**For Bash/Zsh:**

```bash
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
```

**For Fish:**

```text
set -Ux PYENV_ROOT $HOME/.pyenv
pyenv init - | source
```

### Verifying Installation

```bash
# Check if pyenv is properly installed
pyenv --version
# Check current Python version
python --version
# Verify shell integration
pyenv init
```

---

## 3. Core Commands Reference

A quick lookup table for `pyenv`'s primary commands.

| Command           | Description                                                        | Aliases           |
| :---------------- | :----------------------------------------------------------------- | :---------------- |
| `pyenv install`   | Installs a specific Python version.                                | -                 |
| `pyenv uninstall` | Removes an installed Python version.                               | `pyenv uninstall` |
| `pyenv versions`  | Lists all installed Python versions.                               | `pyenv version`   |
| `pyenv version`   | Shows the currently active Python version.                         | -                 |
| `pyenv versions`  | Lists all installed Python versions with indicators.               | -                 |
| `pyenv global`    | Sets the global Python version.                                    | -                 |
| `pyenv local`     | Sets the local project Python version (creates `.python-version`). | -                 |
| `pyenv shell`     | Sets the shell-specific Python version.                            | -                 |
| `pyenv which`     | Shows the path to the Python executable being used.                | -                 |
| `pyenv whence`    | Lists all Python versions that contain a specific command.         | -                 |
| `pyenv init`      | Initializes pyenv for your shell.                                  | -                 |
| `pyenv rehash`    | Regenerates pyenv shims directory.                                 | -                 |
| `pyenv update`    | Updates pyenv and its plugins.                                     | -                 |
| `pyenv doctor`    | Checks for potential pyenv configuration problems.                 | -                 |

---

## 4. Python Version Management

### Basic Version Operations

| Task                           | Command                         | Example                  | Notes                                                     |
| :----------------------------- | :------------------------------ | :----------------------- | :-------------------------------------------------------- |
| **List available versions**    | `pyenv install --list`          | `pyenv install --list`   | Shows all available Python versions for installation.     |
| **Install a specific version** | `pyenv install <version>`       | `pyenv install 3.11.7`   | Downloads, compiles, and installs Python version.         |
| **Install latest patch**       | `pyenv install <major>.<minor>` | `pyenv install 3.11`     | Installs the latest patch version for given major.minor.  |
| **Uninstall a version**        | `pyenv uninstall <version>`     | `pyenv uninstall 3.10.0` | Removes an installed Python version.                      |
| **List installed versions**    | `pyenv versions`                | `pyenv versions`         | Shows all installed versions with current version marked. |
| **Check current version**      | `pyenv version`                 | `pyenv version`          | Shows the currently active Python version.                |

### Version Selection Strategies

| Scope      | Command                  | Example                | Effect                                                     | Priority |
| :--------- | :----------------------- | :--------------------- | :--------------------------------------------------------- | :------- |
| **Global** | `pyenv global <version>` | `pyenv global 3.12.0`  | Sets default Python version for all shells and sessions.   | Lowest   |
| **Local**  | `pyenv local <version>`  | `pyenv local 3.11.0`   | Creates `.python-version` file in current directory.       | Medium   |
| **Shell**  | `pyenv shell <version>`  | `pyenv shell 3.10.0`   | Sets version for current shell session only.               | Highest  |
| **Clear**  | `pyenv global --unset`   | `pyenv global --unset` | Removes global version setting.                            | -        |
| **Clear**  | `pyenv local --unset`    | `pyenv local --unset`  | Removes local version setting (deletes `.python-version`). | -        |
| **Clear**  | `pyenv shell --unset`    | `pyenv shell --unset`  | Removes shell-specific version setting.                    | -        |

### Version Priority

`pyenv` resolves Python versions in this order (highest to lowest priority):

1. **Shell-specific** (`pyenv shell`)

2. **Local project** (`.python-version` file)

3. **Global** (`pyenv global`)

```bash
# Example of priority in action
pyenv global 3.11.0      # Set global to Python 3.11
cd ~/my-project          # Switch to project directory
pyenv local 3.12.0       # Set local to Python 3.12 (creates .python-version)
pyenv shell 3.10.0       # Set shell to Python 3.10
python --version         # Returns Python 3.10.0 (shell takes priority)
# Exit shell and return
exit                    # Exit the shell
cd ~/my-project
python --version        # Returns Python 3.12.0 (local takes priority)
# Change to different directory
cd ~
python --version        # Returns Python 3.11.0 (global takes priority)
```

---

## 5. Advanced Installation Options

### Build Dependencies

| OS                | Dependencies                                                                                                                                                                                          | Installation Command                                                                                                                                                                                                       |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **macOS**         | Xcode Command Line Tools                                                                                                                                                                              | `xcode-select --install`                                                                                                                                                                                                   |
| **Ubuntu/Debian** | 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, git | `sudo apt update && sudo apt install -y 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` |
| **CentOS/RHEL**   | gcc, openssl-devel, bzip2-devel, libffi-devel, readline-devel, sqlite-devel, wget                                                                                                                     | `sudo yum install gcc openssl-devel bzip2-devel libffi-devel readline-devel sqlite-devel wget`                                                                                                                             |
| **Fedora**        | gcc, openssl-devel, bzip2-devel, libffi-devel, readline-devel, sqlite-devel, wget                                                                                                                     | `sudo dnf install gcc openssl-devel bzip2-devel libffi-devel readline-devel sqlite-devel wget`                                                                                                                             |
| **Arch Linux**    | base-devel, openssl, zlib, readline, sqlite                                                                                                                                                           | `sudo pacman -S base-devel openssl zlib readline sqlite`                                                                                                                                                                   |

### Environment Variables for Custom Builds

```bash
# Set custom Python installation prefix
export PYTHON_BUILD_CURL_OPTS="--retry 5 --retry-delay 1"
export PYTHON_BUILD_WGET_OPTS="--tries 5 --wait=1"
# Use custom OpenSSL installation
export OPENSSL_ROOT_DIR=/usr/local/opt/openssl
export LDFLAGS="-L/usr/local/opt/openssl/lib"
export CPPFLAGS="-I/usr/local/opt/openssl/include"
# Use custom Python configuration
export PYTHON_CONFIGURE_OPTS="--enable-optimizations --with-openssl=/usr/local/opt/openssl"
```

### Installing Specific Variants

```bash
# Install with debugging symbols
PYTHON_CONFIGURE_OPTS="--with-pydebug" pyenv install 3.12.0
# Install shared library
PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install 3.12.0
export LD_LIBRARY_PATH="$(pyenv root)/versions/3.12.0/lib"
# Install with custom optimization
MAKE_OPTS="-j4" pyenv install 3.12.0
# Skip installing optional modules
PYTHON_CONFIGURE_OPTS="--without-ensurepip" pyenv install 3.12.0
```

---

## 6. Plugin Management

`pyenv` plugins extend its functionality. Here are the most popular ones:

### Popular Plugins

| Plugin                     | Purpose                                       | Installation Command                                                                                         |
| :------------------------- | :-------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| **pyenv-virtualenv**       | Virtual environment management                | `git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv`             |
| **pyenv-update**           | Auto-update pyenv and plugins                 | `git clone https://github.com/pyenv/pyenv-update.git $(pyenv root)/plugins/pyenv-update`                     |
| **pyenv-which-ext**        | Enhanced `pyenv which` command                | `git clone https://github.com/pyenv/pyenv-which-ext.git $(pyenv root)/plugins/pyenv-which-ext`               |
| **pyenv-doctor**           | Troubleshooting and health checks             | `git clone https://github.com/pyenv/pyenv-doctor.git $(pyenv root)/plugins/pyenv-doctor`                     |
| **python-build**           | Advanced Python build options                 | Usually included with pyenv                                                                                  |
| **pyenv-pip-rehash**       | Automatic shim rehashing after pip install    | `git clone https://github.com/pyenv/pyenv-pip-rehash.git $(pyenv root)/plugins/pyenv-pip-rehash`             |
| **pyenv-default-packages** | Auto-install packages for new Python versions | `git clone https://github.com/pyenv/pyenv-default-packages.git $(pyenv root)/plugins/pyenv-default-packages` |
| **pyenv-win**              | Windows support                               | Used for Windows pyenv-win installation                                                                      |

### Managing Plugins

```bash
# Update all plugins
pyenv update
# Update specific plugin
cd $(pyenv root)/plugins/pyenv-virtualenv
git pull
# List installed plugins
ls -la $(pyenv root)/plugins/
# Remove a plugin
rm -rf $(pyenv root)/plugins/plugin-name
```

---

## 7. Virtual Environment Integration

With `pyenv-virtualenv` plugin, you can create and manage virtual environments that automatically use pyenv-managed Python versions.

### Basic Virtual Environment Management

| Task                            | Command                             | Example                             | Notes                              |
| :------------------------------ | :---------------------------------- | :---------------------------------- | :--------------------------------- |
| **Create virtualenv**           | `pyenv virtualenv <version> <name>` | `pyenv virtualenv 3.12.0 myproject` | Creates virtual environment.       |
| **Create from current version** | `pyenv virtualenv <name>`           | `pyenv virtualenv myproject`        | Uses current Python version.       |
| **List virtualenvs**            | `pyenv virtualenvs`                 | `pyenv virtualenvs`                 | Shows all virtual environments.    |
| **Activate virtualenv**         | `pyenv activate <name>`             | `pyenv activate myproject`          | Activates the virtual environment. |
| **Deactivate virtualenv**       | `pyenv deactivate`                  | `pyenv deactivate`                  | Returns to system Python.          |
| **Delete virtualenv**           | `pyenv uninstall <name>`            | `pyenv uninstall myproject`         | Removes the virtual environment.   |

### Advanced Virtualenv Features

```bash
# Create virtualenv with site-packages from system
pyenv virtualenv --system-site-packages 3.12.0 myproject
# Set local Python version and create virtualenv in one command
pyenv local myproject
# Integrate with existing project structure
mkdir myproject && cd myproject
pyenv virtualenv 3.11.0 myproject
pyenv local myproject  # Creates .python-version and activates
```

### Integration with Common Tools

**With Poetry:**

```bash
# Set Python version first
pyenv local 3.12.0
# Then use Poetry (it will use the pyenv version)
poetry init
poetry install
```

**With Virtualenvwrapper:**

```bash
# pyenv-virtualenvwrapper provides compatibility
pyenv virtualenvwrapper
mkvirtualenv myproject  # Uses pyenv's Python version
```

**With Pipenv:**

```bash
# Set Python version first
pyenv local 3.12.0
# Then use Pipenv (it will use the pyenv version)
pipenv --python 3.12.0
```

---

## 8. Shims and PATH Management

`pyenv` works by inserting a `shims` directory at the front of your `PATH`. These shims are lightweight wrapper scripts that intercept commands and redirect them to the appropriate Python version.

### Understanding Shims

```bash
# Check where shims are located
pyenv init
# Output: export PATH="/home/user/.pyenv/shims:$PATH"
# List all shims
ls $(pyenv root)/shims/
# Check which Python version a command uses
pyenv which python
pyenv which pip
pyenv which pytest
# Check all Python versions that provide a command
pyenv whence python
```

### Maintaining Shims

```bash
# Regenerate shims (run after installing new Python versions)
pyenv rehash
# Check shim health
pyenv doctor
# Manually refresh shims for a specific command
pyenv which python  # This forces rehash for python
```

### PATH Debugging

```bash
# Check your current PATH
echo $PATH
# Verify shims are at the front
echo $PATH | tr ':' '\n' | grep pyenv
# Check which python is being used
which python
type python
command -v python
# Force pyenv to take precedence
export PATH="$(pyenv root)/shims:$PATH"
```

---

## 9. Project-Specific Configuration

### `.python-version` File

The `.python-version` file contains the Python version specification for a project:

```bash
# Content of .python-version file
3.11.7
# Or with patch version specification
3.11
# Or with more complex specification (if using pyenv-ext plugin)
pypy3.9-7.3.12
```

### Project Workflow Examples

**Starting a new project:**

```bash
mkdir my-new-project && cd my-new-project
pyenv local 3.12.0  # Creates .python-version and sets version
python --version    # Verify Python 3.12.0 is active
```

**Cloning an existing project:**

```bash
git clone https://github.com/user/project.git
cd project
python --version    # Automatically uses version from .python-version
```

**Managing multiple project versions:**

```bash
# Project 1 - Python 3.11
cd ~/projects/legacy-project
pyenv versions      # Shows: * 3.11.0 (set by /home/user/projects/legacy-project/.python-version)
# Project 2 - Python 3.12
cd ~/projects/new-project
pyenv versions      # Shows: * 3.12.0 (set by /home/user/projects/new-project/.python-version)
```

### Advanced Configuration

**Multiple versions fallback:**

```bash
# .python-version file can specify multiple versions (pyenv-win behavior)
3.12.0
3.11.7
3.10.0
# pyenv will try versions in order
```

**Development vs Production environments:**

```bash
# Development
pyenv local 3.12.0-dev
# Production deployment
pyenv local 3.12.0
# Or use different Python implementations
pyenv local pypy3.9-7.3.12
```

---

## 10. Integration with Development Tools

### IDE Integration

**VS Code:**

```json
// .vscode/settings.json
{
    "python.defaultInterpreterPath": "~/.pyenv/shims/python",
    "python.terminal.activateEnvironment": false
}
```

**PyCharm:**

- Go to Project Interpreter settings

- Add Local interpreter

- Point to `~/.pyenv/versions/{version}/bin/python`

**Vim/Neovim:**

```text
" .vimrc or init.vim
let g:python_host_prog = expand('~/.pyenv/shims/python')
let g:python3_host_prog = expand('~/.pyenv/shims/python3')
```

### Docker Integration

```dockerfile
# Dockerfile
RUN pyenv install 3.12.0 && pyenv global 3.12.0
ENV PYENV_ROOT="/root/.pyenv"
ENV PATH="$PYENV_ROOT/bin:$PATH"
RUN pyenv rehash
```

### CI/CD Integration

**GitHub Actions:**

```yaml
steps:
  - uses: actions/checkout@v4
  - name: Set up Python
    uses: actions/setup-python@v4
    with:
      python-version: '3.12'
      # Or use a specific version
      python-version: '3.11.7'
```

**GitLab CI:**

```yaml
image: ubuntu:22.04
before_script:
  - apt-get update
  - apt-get install -y curl git gcc make libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
  - curl https://pyenv.run | bash
  - echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
  - echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
  - echo 'eval "$(pyenv init -)"' >> ~/.bashrc
  - . ~/.bashrc
  - pyenv install 3.12.0
  - pyenv global 3.12.0
test:
  script:
    - python --version
    - pip install -r requirements.txt
    - python -m pytest
```

---

## 11. Troubleshooting

### Common Issues and Solutions

| Issue                          | Symptom                                     | Solution                                                                                                         |
| :----------------------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------- |
| **Wrong Python version**       | `python --version` shows unexpected version | 1. Check `pyenv versions`2. Check current directory for `.python-version`3. Check `pyenv shell --unset`          |
| **Command not found**          | `pyenv: command not found`                  | 1. Ensure pyenv is in PATH2. Run `eval "$(pyenv init -)"` in shell3. Check shell config files                    |
| **Build failures**             | Python installation fails during `make`     | 1. Install build dependencies2. Check logs in `/tmp/python-build*.log`3. Try with verbose mode                   |
| **Shim issues**                | `which python` doesn't show pyenv path      | 1. Run `pyenv rehash`2. Check PATH order3. Verify shims directory exists                                         |
| **Virtualenv not activating**  | Virtualenv commands not working             | 1. Install pyenv-virtualenv plugin2. Run `pyenv virtualenvs`3. Try `pyenv activate` instead                      |
| **Global version not working** | Local settings override global              | 1. Check `pyenv versions`2. Remove local settings with `pyenv local --unset`3. Check for `.python-version` files |
| **Shell restart required**     | Changes to config not taking effect         | 1. Restart shell: `exec "$SHELL"`2. Source config: `source ~/.bashrc`3. Check shell: `echo $SHELL`               |

### Diagnostic Commands

```bash
# Comprehensive health check
pyenv doctor
# Check pyenv installation
pyenv --version
pyenv root
echo $PYENV_ROOT
# Check shell integration
pyenv init
echo $PATH | grep pyenv
which python
pyenv which python
# Debug version selection
pyenv version
pyenv versions
cat .python-version 2>/dev/null || echo "No local version file"
pyenv shell --unset
pyenv local --unset
# Check build logs
ls -la /tmp/python-build*.log
tail -50 /tmp/python-build.log
```

### Environment Variables

```bash
# Check environment variables that affect pyenv
echo $PYENV_VERSION
echo $PYENV_SHELL
echo $PYENV_DIR
# Check pyenv settings
pyenv vars
```

---

## 12. Performance and Optimization

### Build Optimization

```bash
# Parallel compilation
MAKE_OPTS="-j$(nproc)" pyenv install 3.12.0
# Use system libraries where available
export PYTHON_CONFIGURE_OPTS="--with-openssl=$(brew --prefix openssl)"
# Cache build dependencies
export PYTHON_BUILD_CURL_OPTS="--retry 3 --retry-delay 5"
export PYTHON_BUILD_WGET_OPTS="--tries 3 --wait=5"
```

### Cache Management

```bash
# Check cache directory
pyenv root/cache
# Clear Python source downloads
rm -rf $(pyenv root)/cache/*
# Set custom cache directory
export PYTHON_BUILD_CACHE_DIR=/path/to/cache
```

### Network Optimization

```bash
# Use specific mirror for faster downloads
export PYTHON_BUILD_MIRROR_URL=https://www.python.org/ftp/python
# Skip certificate verification (not recommended for production)
export PYTHON_BUILD_SKIP_MIRROR=1
```

---

## 13. Migration and Backup

### Exporting/Importing Versions

```bash
# List all installed versions
pyenv versions > pyenv-versions.txt
# Export current environment
pyenv versions --bare > my-python-versions.txt
# Script to install from list
cat my-python-versions.txt | while read version; do
  pyenv install $version
done
```

### Project Migration

```bash
# For each project directory
find . -name ".python-version" -exec cat {} \;
# Backup project Python versions
find . -name ".python-version" -exec sh -c 'echo "{}: $(cat {})"' \;
# Create migration script
cat > migrate-python.sh << 'EOF'
#!/bin/bash
while IFS= read -r line; do
  project=$(dirname "$line")
  version=$(cat "$line")
  echo "Project: $project, Python: $version"
  cd "$project"
  pyenv install "$version"
  pyenv local "$version"
  cd -
done < <(find . -name ".python-version")
EOF
```

---

## 14. Automation and Scripts

### Automatic Version Switching

```bash
# Auto-switch based on requirements.txt
cat > .auto-version << 'EOF'
#!/bin/bash
if [ -f requirements.txt ]; then
  # Parse Python version from requirements.txt
  version=$(grep -E '^python[-~]?=?.*[0-9]' requirements.txt | head -1)
  if [ ! -z "$version" ]; then
    # Extract version number and set it
    pyenv install -s $(echo "$version" | sed 's/python[-~]?=//')
    pyenv local $(echo "$version" | sed 's/python[-~]?=//')
  fi
fi
EOF
# Add to git hook
chmod +x .auto-version
echo ".auto-version" >> .git/hooks/pre-commit
```

### Pre-commit Hooks

```bash
# .git/hooks/pre-commit
#!/bin/bash
# Ensure Python version consistency
current_version=$(pyenv version-name)
required_version=$(cat .python-version 2>/dev/null)
if [ ! -z "$required_version" ] && [ "$current_version" != "$required_version" ]; then
  echo "Warning: Python version mismatch"
  echo "Required: $required_version"
  echo "Current: $current_version"
  echo "Switching to required version..."
  pyenv local "$required_version"
fi
```

---

## 15. Security Considerations

### Safe Installation Practices

```bash
# Verify pyenv installer authenticity
# Download installer and check signature before running
curl -s https://pyenv.run | sh -s -- --verify-download-signatures
# Use specific pyenv version
git clone https://github.com/pyenv/pyenv.git ~/.pyenv
cd ~/.pyenv
git checkout v2.3.32  # Use latest stable release
```

### Build Security

```bash
# Verify checksums (when available)
export PYTHON_BUILD_VERIFY_CHECKSUM=1
# Use trusted mirrors only
export PYTHON_BUILD_MIRROR_URL=https://www.python.org/ftp/python
# Avoid running as root
# Always use pyenv as regular user
```

---

### Sources

This cheatsheet was synthesized from the following official and community resources:

- [Pyenv Official Documentation](https://github.com/pyenv/pyenv)

- [Pyenv Installation Guide](https://github.com/pyenv/pyenv#installation)

- [Pyenv-Win GitHub Repository](https://github.com/pyenv-win/pyenv-win)

- [Pyenv Virtualenv Plugin](https://github.com/pyenv/pyenv-virtualenv)

- [Python Build Dependencies](https://github.com/pyenv/pyenv/wiki#suggested-build-environment)

- [Pyenv Commands Reference](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md)

- [Common Python Build Problems](https://github.com/pyenv/pyenv/wiki/Common-build-problems)

- [Managing Multiple Python Versions with Pyenv](https://realpython.com/intro-to-pyenv/)

- [Pyenv Cheatsheet by Saghul](https://saghul.github.io/pyenv/)

- [Professional Python Development with Pyenv](https://testdriven.io/blog/python-development-with-pyenv/)

---

# Quick Reference Card

**Essential Commands at a Glance:**

| **Task**            | **Command**                                  | **Example**                    |            |
| :------------------ | :------------------------------------------- | :----------------------------- | :--------- |
| Install pyenv       | `curl [https://pyenv.run](https://pyenv.run) | bash`                          | -          |
| List versions       | `pyenv install --list`                       | `pyenv install --list          | grep 3.12` |
| Install Python      | `pyenv install <version>`                    | `pyenv install 3.12.0`         |            |
| Set global          | `pyenv global <version>`                     | `pyenv global 3.12.0`          |            |
| Set local           | `pyenv local <version>`                      | `pyenv local 3.11.0`           |            |
| Set shell           | `pyenv shell <version>`                      | `pyenv shell 3.10.0`           |            |
| List installed      | `pyenv versions`                             | -                              |            |
| Check version       | `pyenv version`                              | -                              |            |
| Create virtualenv   | `pyenv virtualenv <ver> <name>`              | `pyenv virtualenv 3.12.0 venv` |            |
| Activate virtualenv | `pyenv activate <name>`                      | `pyenv activate venv`          |            |
| Update pyenv        | `pyenv update`                               | -                              |            |
| Rehash shims        | `pyenv rehash`                               | -                              |            |

**Path Priority (Highest to Lowest):**

1. `pyenv shell <version>`

2. `pyenv local <version>` (`.python-version` file)

3. `pyenv global <version>`

4. System Python (fallback)