How to Install and Manage Python Versions with pyenv on Windows, macOS, and Linux

Install pyenv on Windows

Step 1: Check existing Python

Windows usually does not have Python installed. If you have one, uninstall it (unless a project depends on it). Verify with python -V which should show the version, e.g., Python 3.9.10. After uninstalling, run the command again; it should report that Python is not found.

Step 2: Install pyenv

The official pyenv does not support Windows, but the pyenv-win fork works well. Install it via PowerShell (run as administrator):

Set-ExecutionPolicy RemoteSigned

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; & "./install-pyenv-win.ps1"

After installation, reopen PowerShell and verify with pyenv --version (e.g., pyenv 2.64.11).

Step 3: Install Python with pyenv

List available Python versions: pyenv install -l Install a specific version, e.g., 3.9.10: pyenv install 3.9.10 After installation, verify available versions:

pyenv versions

Step 4: Choose Python version

Set the global version: pyenv global 3.9.10 Confirm with python -V (should show Python 3.9.10).

Step 5: PATH handling

pyenv‑win automatically adds the selected Python to PATH. If the path is missing, you can manually check the environment variables.

Step 6: Update pyenv‑win

Run the update script: &"${env:PYENV_HOME}\install-pyenv-win.ps1" Verify the new version with pyenv --version (e.g., pyenv 2.64.12).

Install pyenv on macOS

Step 1: Check existing Python

macOS ships with Python 3 if Xcode Command Line Tools are installed. Verify with python3 -V. If the tools are missing, the system will prompt you to install them.

Step 2: Install Homebrew

Check Homebrew with brew -v. If not present, install it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installation, add Homebrew to your PATH as instructed.

Step 3: Install pyenv via Homebrew

brew update

brew install pyenv

Step 4: Configure shell for pyenv

Determine your shell (e.g., zsh) and add the following lines to the appropriate rc file ( .zshrc, .zprofile, or .zlogin):

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

Reload the shell with exec "$SHELL" and verify pyenv --version (e.g., pyenv 2.3.0).

Step 5: Install build dependencies

brew install openssl readline sqlite3 xz zlib tcl-tk

Step 6: Install Python with pyenv

pyenv install -l

pyenv install 3.9.10

pyenv install 3.12.5

pyenv versions

Step 7: Choose Python version

pyenv global 3.9.10

Confirm with python -V.

Step 8: PATH handling

pyenv manages PATH automatically; you can inspect your shell rc files to see the exported variables.

Step 9: Update pyenv on macOS

brew upgrade pyenv

pyenv --version

Install pyenv on Linux (Ubuntu)

Step 1: Check existing Python

Ubuntu usually includes Python 3. Verify with python3 -V. No need to uninstall.

Step 2: Install required dependencies

sudo apt update
sudo apt 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 git gcc

Step 3: Install pyenv

curl https://pyenv.run | bash

Step 4: Configure shell for pyenv

Add the following to .bashrc, .bash_profile, and .profile (adjust for your shell if needed):

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
# repeat for .bash_profile and .profile

Reload the shell with exec "$SHELL" and verify pyenv --version (e.g., pyenv 2.3.0).

Step 5: Install Python with pyenv

pyenv install -l

pyenv install 3.9.10

pyenv install 3.12.5

pyenv versions

Step 6: Choose Python version

pyenv global 3.9.10

Confirm with python -V.

Step 7: PATH handling

pyenv adds its bin directory to PATH automatically; you can view the export lines in your rc files.

Step 8: Update pyenv on Ubuntu

Two methods are shown: pyenv update or

cd ~/.pyenv
git pull

Both report “Already up to date.”