How to Change Python Version on Mac: Easy Step-by-Step Guide
Managing multiple Python versions on a Mac is a common requirement for developers working on different projects with varying dependency needs. The system Python that comes pre-installed with macOS is best left untouched, as it is used by the operating system for critical tasks. Instead, the goal is to install and manage additional Python versions without disrupting the core functionality of your machine.
Understanding the macOS Python Environment
Before diving into installation methods, it is important to understand the distinction between the system Python and user-installed versions. Historically, macOS included Python 2.7, but recent versions no longer ship with any Python pre-installed. If you run python in Terminal and see a version like 2.7.16, you are interacting with the legacy system interpreter. Most modern workflows target Python 3, which requires manual installation. Ignoring this distinction helps avoid permission errors and broken system utilities down the line.
Installing a Version Manager
The most efficient way to handle multiple Python versions is by using a version manager. These tools allow you to switch between interpreters seamlessly and manage virtual environments. Two dominant solutions in the ecosystem are pyenv and asdf.
Why Use pyenv?
pyenv is lightweight and purpose-built specifically for Python. It hooks into your shell and intercepts the python command, redirecting it to the version you specify. This makes it ideal for developers who want precise control over their Python binaries. It works by compiling Python from source, which ensures optimal performance and compatibility with macOS.
Alternative: Using asdf
For developers who work with multiple programming languages (such as Node.js or Ruby), asdf is a more generic version manager. It uses a plugin system, meaning you install one tool to manage the versions of all your runtimes. If your workflow is polyglot, asdf provides a unified interface that keeps your terminal commands consistent across different languages.
The Installation Process
Assuming you have Homebrew installed, the process of setting up your version manager becomes straightforward. Homebrew is the standard package manager for macOS, and it simplifies the installation of dependencies like compilers and SSL certificates, which are necessary for building Python from source.
Step-by-Step with Homebrew
To install pyenv via Homebrew, you search for the formula and link it to your system. Once installed, you add the shim path to your shell profile. This path is where the executable scripts live; without it, your shell will not recognize the pyenv command. The installation typically involves running brew update, followed by brew install pyenv.
| Manager | Best For | Performance |
|---|---|---|
| pyenv | Python-only workflows | Fast (uses system python) |
| asdf | Multi-language environments | Slightly slower (plugin overhead) |
Installing the Python Versions
With the version manager configured, you can now install the specific Python releases you need. This step downloads the source code and compiles it into a binary that macOS can execute. You can list available versions using a command like pyenv install --list, and then install a specific one using pyenv install 3.9.18.
It is recommended to install the latest patch version of any minor release (e.g., 3.9.x rather than just 3.9.0) to benefit from security patches and bug fixes. Once installed, the versions reside in a directory within your user folder, eliminating the need for sudo privileges and keeping the system clean.
Setting the Global and Local Versions
After installation, you must tell your shell which version to use by default. The global command sets the default Python version for your entire user account. This is the version you will get when you open a new terminal window on your Mac.
Additionally, you can set a local version on a per-project basis. By navigating to a project directory and running pyenv local 3.11.8 (or using a .python-version file), you ensure that the correct interpreter is used whenever you work on that specific codebase. This prevents version conflicts when you have multiple projects open simultaneously.
Verifying and Managing Your Setup
Finally, you should verify that the version switch was successful. Running python --version should now display the version you set as global or local. If the output still points to an old path, you need to check your shell configuration file (like .zshrc or .bash_profile) to ensure the pyenv shims are initialized correctly.
For maintenance, you can update your version manager and reinstall Python versions as needed. If a specific version causes compatibility issues, you can uninstall it using pyenv uninstall 3.9.18. This flexibility is the core advantage of using a version manager, as it gives you the agility to adapt your environment to any project requirement instantly.