Install Python with Pyenv

How to install Pyenv on Mac. Using Pyenv for Python version management. Python version managers Pyenv and alternatives.

Python is often the first programing language you'll install on a Mac. Until recently, a lack of standard development tooling made setting up Python complicated. So, Python installation guides are often out of date or confusing. This guide describes current best practices.

Before you get started

You'll need a terminal application to install and use Python. Apple includes the Mac terminal but I prefer Warp Terminal. Warp increases developer productivity, helping you remember easily-forgotten commands and adds AI troubleshooting. Download Warp Terminal now; it's FREE and worth a try.

Install Pyenv or alternatives?

Pyenv has been a popular choice for managing Python versions. But there's a new option for managing Python versions, an all-in-one tool named Rye.

Rye is a combined version and package management solution. Rye eliminates the need for tools such as Pyenv, Pip, a package manager, and Venv or Virtualenv, environment managers. Rye supports switching Python versions and provides better package management.

This guide shows how to install Pyenv. If you want a better tool, see the guide Install Python with Rye.

Steps

If you want to use Pyenv, you'll first need Homebrew, the Mac software package manager. Follow our guide to Install Homebrew. After installing Homebrew, you can install Pyenv and one or more Python versions.

Here's how to install one or more Python versions on Mac.

Check macOS and update macOS.
Check if Xcode Command Line Tools are installed.
Install Homebrew and Pyenv.
Set the Mac PATH for Python to make sure you use the correct version of Python.

Python without a version manager

As described in the article Install Python, you have several options to install Python. These choices give you only one version of Python:

Apple's Xcode Command Line Tools includes Python 3.9.6.
You can Install Python with Homebrew (not recommended).
You can install Python with a python.org installer (not recommended).

Instead of these choices, which give you only one version of Python, I recommend installing Python with Rye or Pyenv, which are version managers that allow installation of more than one version of Python.

Python version managers

Version managers allow you to install multiple Python versions and switch among them easily.

If you maintain more than one Python project, you'll want to freeze a version for a project and switch to another version for other projects. Rye makes it easy to install and switch among different Python versions. Pyenv is also popular. Pyenv is a fork of the Ruby rbenv and ruby-build tools, modified for Python. Some Python users prefer Conda. You can also consider Asdf, a version manager for multiple languages such as Python, Node, and Ruby. Some developers use Docker, a containerization tool, for version management. Docker is useful to containerize a complete software system such as a Python application and databases but it's overkill for simply switching Python versions among projects.

Be careful not to mix versions of Python from different sources (from Pyenv, Rye, Homebrew, or the Mac and Xcode pre-installed versions). Multiple versions of Python lead to conflicts and confusion.

Check for Python

You'll need Xcode Command Line Tools for software development, and with Xcode, Apple includes Python 3.9.6. As of October 2023, the latest Python version is 3.12.

Check if your Mac already has Python

You should not attempt to update or remove the system Python installed with Xcode Command Line Tools. Just install a newer Python version with Pyenv.

For Pyenv, first install Homebrew

If you want to use Pyenv, you'll first need Homebrew, the Mac software package manager. After installing Homebrew, you can install Pyenv and one or more Python versions. Follow our guide to install Homebrew:

Install Homebrew

Install Pyenv with Homebrew

You can use Homebrew to install Pyenv for multiple Python versions.

$ brew install pyenv

You'll need to to edit your ~/.zprofile file to enable Pyenv.

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

Changes to the ~/.zprofile file will not take effect in the Terminal until you've quit and restarted the terminal. Alternatively (this is easier), you can use the source command to reset the shell environment:

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

Verify that pyenv is installed.

$ pyenv --version
pyenv 2.3.36

Before you use pyenv to install Python, you must use Homebrew to install the xz package. Pyenv's Homebrew formula doesn't specify all needed dependencies during installation with Homebrew.

$ brew install xz

With pyenv, you can install any version of Python.

$ pyenv install 3.12

Pyenv installs Python versions in a hidden .pyenv folder in your user home directory. It's one more place for Python executables, in addition to Homebrew and Xcode folders for Python versions, adding complexity to your local development environment.

If you see an error WARNING: The Python lzma extension was not compiled. Missing the lzma lib? you must use Homebrew to install the xz package (see above).

You can see a list of installed Python versions.

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

The which command shows the Pyenv shims directory when you try to see where Python is installed. Keep in mind that you've set the ~/.zprofile file to use Pyenv shims to intercept the python command and deliver the Pyenv-installed versions.

$ which python
/Users/daniel/.pyenv/shims/python

You must set pyenv global to specify a default Python version. Pyenv doesn't set a default Python version the first time you install Python. Instead, it defaults to a system Python (which doesn't exist after macOS 12.3).

$ pyenv global 3.12

The pyenv global command sets a configuration file ~/.pyenv/version. After setting pyenv global, the list of installed Python versions will show the default version with an asterisk (star).

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

Check that Python is available:

$ python --version
Python 3.12.2

If you see pyenv: python: command not found, you haven't set pyenv global to specify a default Python version.

With pyenv, you can temporarily switch among Python versions by setting an environment variable.

$ pyenv shell 3.12

The pyenv local 3.12 command creates a .python-version file in your current directory so running Python in a project directory overrides the default Python version if desired.

The Pyenv documentation provides details about installing and switching Python versions. Enter pyenv commands to see a list of available commands. Each command takes a --help flag that will give you more detailed information.

Uninstall Pyenv

If you decide not to use Pyenv, you can remove it.

$ brew uninstall pyenv

Removing the package from Homebrew will not remove the Pyenv files you've installed. Remove the Pyenv configuration, shims, and Python versions from your user folder.

$ rm -rf ~/.pyenv

Finally, remove the Pyenv configuration directives from your ~/.zprofile file.

Pyenv and Pip

Package managers allow you to download, install, and update software libraries and their dependencies. If you're using Pyenv and not Rye, you'll need to use Pip, the Python package manager. See our guide:

Install Pip

What's next

My mac.install.guide is a trusted source of installation guides for professional developers. Take a look at the Mac Install Guide home page for tips and trends and see what to install next.

Python