In this post I’ll explain how to install Python using PyEnv on a macOS machine.

This tutorial is also available in video form here:

What is PyEnv and why use it?

macOS comes with Python pre-installed.

However, the version installed is usually 2.7, which was deprecated on January 1st 2020.

So you might be thinking: Why not remove the old version (2.7) and replace it with a newer version like 3.9 using the traditional installation method?

This is not recommended because there may be some software on your macOS which requires Python 2.7 to run.

In other words, if you remove this version — things may break.

Also, if you use Python professionally, you’ll likely need to use specific versions for different projects, so it’s useful to be able to switch versions as needed.

Enter PyEnv

PyEnv is a useful open source tool for managing multiple Python versions on your machine.

Using this tool, you can take advantage of all the latest features of Python 3.9, meanwhile ensuring that software requiring older versions of Python (like 2.7) continue to work on your machine.

In this tutorial, I’ll explain:

1. How to install and configure PyEnv
2. How to install a specific version of Python on your machine
3. How to choose which version of Python you want to use for a specific project

Installing Homebrew

We’ll install PyEnv using a tool called Homebrew.

If you haven’t used it before, Homebrew is a popular package manager for macOS.

To install it, copy the line below and paste it into your Terminal window:

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

This one-line command (taken from the brew.sh website) will download and run a script that will install Homebrew on your machine.

You’ll need to enter your administrator password and follow the on-screen instructions:

The installation can take a few minutes.

Once it’s done, you should see something like this:

Installing PyEnv using Homebrew

Once Homebrew is installed, we can use it to install PyEnv.

This can be done by running the command below:

brew install pyenv

In-case you’re curious, I’ll translate the command below:

• brew – this is the package manager we installed above
• install – this is the command that tells (Home)brew that we want to install something
• pyenv – this is the name of the package we want to install (Tip: you can find other packages by using the search on brew.sh)

Once installation is complete, you’ll see something like this:

Important! Take note of the two outputs highlighted above (they may be different on your machine).

Configure PyEnv

Now we need to configure PyEnv so it loads when we open our Terminal.

What you see may be different from the screenshot above, because the output depends on your Terminal configuration.

For example, instead of ~/.zshrc, your may see ~/.profile or ~/.bashrc.

What if you closed the window or don’t see any output?

Don’t worry, it happens… Simply open a new Terminal and run the below command to show it again:

pyenv init

Next we need to add the line starting with “eval” to the file path displayed after “# the following to”.

Start by copying the contents of the “eval” line to your clipboard (highlight it, right click and select Copy):

Then, type:

nano <path displayed>

For example, if you see what’s displayed in the screenshot above, you would type:

nano ~/.zshrc

This will open the file in the nano text editor, which will look like this:

If your file already contains text, then use the down arrow key to navigate to the end of the file (do not modify existing lines).

Paste the eval line into the file, like this:

Next, press Control + X, type Y and press Enter when prompted for the file name.

Now PyEnv is installed and configured, exit and reload the Terminal.

Why do we need to do this?

PyEnv is a tool that is used through the Terminal.

It works by telling the Terminal which Python installation should be used, based on certain criteria such as the default configured or certain files available in the directory you’re working from.

For PyEnv to be able to do this, we must run some setup code every time you open a Terminal instance.

By performing the steps above, we are configuring the Terminal to run this code for every new window.

Install Python with PyEnv

Next we can install Python using PyEnv.

To do this, run the following command:

pyenv install 3.9.1 

Tip: You can replace 3.9.1 with any available Python version listed on the Python website.

The installation can take a few minutes.

Once complete, the output should look something like this:

Set default Python version

There are multiple ways to set a Python version using PyEnv.

Each one is explained in the official documentation.

In this tutorial, we’ll set it using the ~/.pyenv/version file.

To set this, type the following command:

echo 3.9.1 > ~/.pyenv/version

Tip: The 3.9.1 in the command above must correspond to an available installed version.

For example, the screenshot below shows how you would set the version to 3.8.2:

Finally, verify the correct version is installed by running the following:

python --version

The output should display the version set above (eg: 3.9.1).

That’s how to install, configure and use Python on macOS using PyEnv.

This tutorial is an excerpt from our course: Python for Beginners: Learn how to code properly in 2021.