Install Python with Pyenv on MacOS

This guide walks you through installing and managing multiple Python versions on your macOS system using Pyenv. Pyenv is an excellent tool for developers who need to work with different Python environments without conflicts.

Prerequisites: Install Homebrew

Before you can install Pyenv, you'll need Homebrew, the popular package manager for macOS.

Install Pyenv with Homebrew

Once Homebrew is set up, you can install Pyenv with a simple command:

$ brew install pyenv

Configure Your Shell for Pyenv

To ensure Pyenv works correctly, you'll need to add some configuration to your shell's profile file. For most modern macOS systems, this is ~/.zprofile. Alternatively, you could use ~/.zshrc (refer to .zshrc or .zprofile for more details on which to choose).

Add the following lines to the very end of your ~/.zprofile file:

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

After modifying the file, you'll need to apply the changes. The easiest way is to run source ~/.zprofile in your terminal, or simply quit and restart your Terminal application.

$ source ~/.zprofile # Or just restart your terminal

Verify Pyenv Installation

Confirm that Pyenv is installed and accessible by checking its version:

$ pyenv --version

You should see output similar to:

pyenv 2.3.36

Install Python Versions with Pyenv

Before you start installing Python versions with Pyenv, it's crucial to install the xz package using Homebrew. This package is a critical dependency for compiling certain Python extensions (like lzma) and isn't always automatically handled by Pyenv's Homebrew formula.

$ brew install xz

Now you're ready to install any Python version you need! For example, to install Python 3.13:

$ pyenv install 3.13

Note: Pyenv installs Python versions into a hidden .pyenv folder within your user home directory (~/.pyenv). This means you'll have another location for Python executables, in addition to any versions installed by Homebrew or Xcode, which can add complexity to your development environment.

If you encounter an error like WARNING: The Python lzma extension was not compiled. Missing the lzma lib?, it's a strong indication that you missed the brew install xz step mentioned above.

Set a Global Python Version

Pyenv doesn't automatically set a default Python version after your first installation. You need to explicitly tell Pyenv which version to use globally. For example, to set Python 3.13 as your default:

$ pyenv global 3.13

This command creates a configuration file at ~/.pyenv/version. After setting the global version, listing your Pyenv versions again will show the default marked with an asterisk:

$ pyenv versions
system
* 3.13.3 (set by /Users/daniel/.pyenv/version)

Now, verify that the correct Python version is active:

$ python --version

You should see:

Python 3.13.3

If you see pyenv: python: command not found, it means you haven't set a global Python version with pyenv global.