Configure macOS to Use Homebrew Python: A Step-by-Step Guide (2026)

Python is a versatile programming language widely used for various applications, from web development to data analysis. macOS comes pre-installed with an older version of Python, typically Python 2.7, which is no longer supported. To take advantage of the latest Python features and security updates, many developers prefer to install Python using Homebrew, a popular package manager for macOS. However, configuring macOS to use the Homebrew-installed Python can be tricky. This guide will walk you through the process step-by-step, ensuring your system is set up correctly.

Key Takeaways

• Learn how to install and configure Python using Homebrew on macOS.
• Understand how to update your shell's PATH environment variable.
• Resolve common issues related to Python version conflicts.
• Ensure your macOS uses the correct Python interpreter by default.
• Troubleshoot potential errors during the configuration process.

Prerequisites

• A macOS system with administrative access.
• Homebrew installed on your macOS. If not, you can install it by following the official Homebrew installation guide.
• Basic understanding of terminal commands and shell configuration files.

Step 1: Install Python Using Homebrew

First, ensure that you have Homebrew installed on your macOS. Open your Terminal and run:

brew update

This command updates Homebrew to its latest version, ensuring you have access to the most recent formulae. Next, install Python:

brew install python

Homebrew will download and install the latest Python version, typically Python 3.x. You can verify the installation by running:

python3 --version

The output should display the version number of the newly installed Python.

Step 2: Update Shell Configuration

To ensure your system uses the Homebrew-installed Python by default, you need to update your shell's configuration file. Depending on your shell, this file could be ~/.bash_profile, ~/.zshrc, or another configuration file. For this guide, we'll assume you're using bash. Open the file in a text editor:

nano ~/.bash_profile

Add the following line to the file:

export PATH="/usr/local/opt/python/libexec/bin:$PATH"

This line ensures that the Homebrew-installed Python is prioritized in your PATH. Save the file and exit the editor. To apply the changes, run:

source ~/.bash_profile

Step 3: Verify the Configuration

After updating your shell configuration, verify that your system is using the correct Python interpreter:

which python

The output should indicate the path to the Homebrew-installed Python, typically /usr/local/bin/python.

Additionally, check the Python version:

python --version

If everything is configured correctly, the version number should match the Homebrew-installed Python version.

Common Errors/Troubleshooting

Issue: Python Version Not Updating

If your terminal still shows the older Python version after following the steps above, ensure you've correctly updated your PATH in the shell configuration file and sourced it. Additionally, check for typos in the file path.

Issue: Command Not Found

If you encounter a 'command not found' error, verify that Homebrew is correctly installed and your PATH includes Homebrew's binary folder.

Conclusion

By following this guide, you should have successfully configured your macOS to use the Homebrew-installed Python version by default. This setup ensures you have access to the latest Python features and enhancements, improving your development experience. Should you encounter any issues, refer back to the troubleshooting section or consult the official Homebrew documentation.

Frequently Asked Questions

Why is my macOS still using Python 2.7?

You may not have updated your PATH correctly or sourced the shell configuration file. Ensure the correct file path is set in your shell's configuration.

How do I switch back to the system Python?

Remove or comment out the line that modifies the PATH in your shell configuration file and source it again.

Is it safe to remove the system Python?

No, it's not recommended to remove the system Python as it might be required by macOS for some system tasks.

Can I use multiple Python versions on macOS?

Yes, you can use tools like pyenv to manage multiple Python versions on your system.

Frequently Asked Questions

Why is my macOS still using Python 2.7?

You may not have updated your PATH correctly or sourced the shell configuration file. Ensure the correct file path is set in your shell's configuration.

How do I switch back to the system Python?

Remove or comment out the line that modifies the PATH in your shell configuration file and source it again.

Is it safe to remove the system Python?

No, it's not recommended to remove the system Python as it might be required by macOS for some system tasks.

Can I use multiple Python versions on macOS?

Yes, you can use tools like pyenv to manage multiple Python versions on your system.