How to Install Python 3 on Mac – Brew Install Update Tutorial

While Mac OS comes with Python pre-installed, it‘s an outdated Python 2.7 release from 2010. Python 2 was officially deprecated in 2020, with support ending January 1, 2020. Currently, over 95% of Python developers have migrated to using Python 3.x, which has been actively developed with new features and improvements over the past decade.

As of May 2023, the latest Python versions are 3.11.3 and 3.12.0a5. Python 3.12.0 will be officially released in October 2023 with exciting new features like a faster interpreter, enhanced error messages, and more.

If you try running the pre-installed python command in Terminal, you‘ll see a warning message:

WARNING: Python 2.7 is not recommended.
This version is included in macOS for compatibility with legacy software. 
Future versions of macOS will not include Python 2.7.
Instead, it is recommended that you transition to using ‘python3‘ from within Terminal.

The Quick Way to Run Python 3

If you just need to run a quick Python 3 command or script, you can use python3 in your Terminal:

python3 my_script.py

This will run the default Python 3.x version included with your current macOS release. However, it‘s best practice to manage your Python versions properly using pyenv. Let‘s walk through how to get that set up.

Installing Homebrew Package Manager

Homebrew is the de facto package manager for macOS. It allows you to easily install tools and libraries through the command line.

Open the Terminal and run this command:

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

The installer will prompt for your password since it needs admin permissions. Your password will not be visible when typing for security reasons. After reviewing what the script will do, press RETURN to continue.

The installation may take a few minutes. Once finished, you‘re ready to brew install packages!

Using pyenv to Manage Python Versions

pyenv is a popular tool to manage multiple Python versions on the same machine. This is useful when working on projects with different Python version requirements.

Install pyenv using Homebrew:

brew install pyenv

Now you can install the latest Python version:

pyenv install 3.11.3

Feel free to specify a different version, like an older 3.10.x or 3.9.x release.

The install step can take some time as it builds Python from source. Sit back and grab a coffee.

Troubleshooting pyenv Install

If you run into an error like "C compiler cannot create executables" during the Python build, you may need to install or update Xcode, Apple‘s developer tools.

Xcode includes necessary C libraries and compilers used when building packages from source. You can get the latest version of Xcode (13.3.1 as of May 2023) from the Apple Developer site. It‘s a large 12.6 GB download, so you may want to start it before bed.

After updating Xcode, the pyenv install command should succeed when retried. Contact me if you still have issues!

Setting Up Your Shell‘s PATH for pyenv

For pyenv to work properly, you need to add its directories to your shell‘s PATH environment variable. This tells your system where to look for Python executables.

When you run a command like python or pip, your shell searches the directories listed in PATH in order, using the first matching executable.

pyenv works by inserting a directory of shims at the front of your PATH. Shims are lightweight executables that delegate to pyenv to determine which Python version to use.

To set this up, first add the following lines to your shell‘s startup configuration file. This is ~/.bash_profile for Bash:

echo ‘export PYENV_ROOT="$HOME/.pyenv"‘ >> ~/.bash_profile
echo ‘export PATH="$PYENV_ROOT/bin:$PATH"‘ >> ~/.bash_profile

Or ~/.zshrc for ZSH:

echo ‘export PYENV_ROOT="$HOME/.pyenv"‘ >> ~/.zshrc
echo ‘export PATH="$PYENV_ROOT/bin:$PATH"‘ >> ~/.zshrc 

Then add pyenv‘s init script to your shell startup:

For Bash:

echo -e ‘if command -v pyenv 1>/dev/null 2>&1; then\n  eval "$(pyenv init -)"\nfi‘ >> ~/.bash_profile

For ZSH:

echo -e ‘if command -v pyenv 1>/dev/null 2>&1; then\n  eval "$(pyenv init --path)"\n  eval "$(pyenv init -)"\nfi‘ >> ~/.zshrc

Restart your shell for the changes to take effect:

exec "$SHELL"

Now pyenv is fully configured and ready to use.

Setting the Global Python Version

You can set the global default Python version for your system using:

pyenv global 3.11.3

This version will be used automatically when you run python.

Verify it worked:

$ python -V
Python 3.11.3

You did it! Python is now up and running on your Mac.

Other Fun Python Things to Install with Homebrew

Here are some other helpful Python packages you may want to brew install:

• ipython: A powerful interactive Python shell
• python-tk: Tkinter GUI toolkit
• python-tabulate: Tool for pretty-printing tabular data
• ansible: IT automation tool (Python powered)
• aws-shell: CLI for AWS services
• pgcli: CLI for PostgreSQL databases

Browse the 9000+ Python packages available: brew search python

Leveraging pyenv Fully

pyenv has many other nifty features, like specifying Python versions per project or switching between versions.

To use a specific Python version in the current dir and subdirs:

pyenv local 3.9.12

To switch to a different installed version temporarily:

pyenv shell 3.10.10

I highly recommend checking out the full pyenv command reference.

Using pyenv with Virtual Environments

Virtual environments allow you to install Python packages in an isolated directory to avoid conflicts. They are an essential tool for Python development.

With pyenv, the recommended tool for creating virtual environments is pyenv-virtualenv.

Install it with Homebrew:

brew install pyenv-virtualenv

Add the pyenv-virtualenv init to your shell startup file:

For Bash:

echo ‘eval "$(pyenv virtualenv-init -)"‘ >> ~/.bash_profile

For ZSH:

echo ‘eval "$(pyenv virtualenv-init -)"‘ >> ~/.zshrc  

Then restart your shell:

exec "$SHELL"

Now you can create virtualenvs with ease:

pyenv virtualenv 3.11.3 my-project

To use a virtualenv:

pyenv activate my-project

To deactivate and return to the system Python:

pyenv deactivate

pyenv and pyenv-virtualenv are a dynamic duo for Python development!

Keeping Python Up to Date

As new Python releases come out, you can install them using:

pyenv install 3.12.0

Then update your global version:

pyenv global 3.12.0 

And update any virtualenvs:

pyenv virtualenv 3.12.0 my-project

It‘s good practice to stay reasonably up to date for the latest features, performance, and security fixes.

Enjoy Your Python Powers!

You now have a professional Python setup on your Mac using pyenv and Homebrew. Go forth and code amazing things!

If you have any other questions, feel free to reach out. I‘m always happy to help a fellow Python developer.

Happy coding!