Manage Multiple Python Versions with pyenv

Beginner10 min

Install and switch between multiple Python versions on the same machine using pyenv, with per-project version pinning.

Prerequisites

-macOS, Linux, or WSL (pyenv does not run natively on Windows)

Steps

Install pyenv

Install pyenv and its plugins (pyenv-virtualenv, pyenv-update). The installer adds pyenv to your home directory at ~/.pyenv.

$ curl https://pyenv.run | bash

After installation, you must add pyenv to your shell PATH. Follow the instructions printed by the installer to update your .bashrc or .zshrc.

List available Python versions

Show all available CPython 3.x versions that can be installed. The list includes stable releases and pre-release versions.

$ pyenv install --list | grep '^ *3\.'

Look for the latest stable version (e.g., 3.12.x or 3.13.x) without a, b, or rc suffixes.

Install a specific Python version

Download and compile the specified Python version. It is installed to ~/.pyenv/versions/ and does not affect your system Python.

$ pyenv install 3.12.7

Set the global default Python version

Set the default Python version used in all shells. This writes to ~/.pyenv/version.

$ pyenv global 3.12.7

Set a per-project Python version

Pin a specific Python version for the current directory by creating a .python-version file. pyenv automatically switches versions when you enter this directory.

$ pyenv local 3.11.9

Commit .python-version to your repository so all team members use the same Python version.

Verify the active Python version

Display which Python version pyenv has selected and confirm that the python command resolves to it.

$ pyenv version && python --version

Full Script

full-script.sh

#!/bin/bash
# pyenv setup and Python version management
set -e

# Install pyenv if not present
if ! command -v pyenv &> /dev/null; then
  curl https://pyenv.run | bash
  export PATH="$HOME/.pyenv/bin:$PATH"
  eval "$(pyenv init -)"
fi

PYTHON_VERSION=${1:-3.12.7}

echo "Installing Python $PYTHON_VERSION..."
pyenv install -s "$PYTHON_VERSION"
pyenv global "$PYTHON_VERSION"

echo "Active Python:"
pyenv version
python --version
pip --version

echo "pyenv setup complete with Python $PYTHON_VERSION."

FAQ

Discussion

Loading comments...

#!/bin/bash # pyenv setup and Python version management set -e # Install pyenv if not present if ! command -v pyenv &> /dev/null; then curl https://pyenv.run | bash export PATH="$HOME/.pyenv/bin:$PATH" eval "$(pyenv init -)" fi PYTHON_VERSION=${1:-3.12.7} echo "Installing Python $PYTHON_VERSION..." pyenv install -s "$PYTHON_VERSION" pyenv global "$PYTHON_VERSION" echo "Active Python:" pyenv version python --version pip --version echo "pyenv setup complete with Python $PYTHON_VERSION."