Mastering Python Installation on macOS with Homebrew and Pyenv

Installing Python on macOS can feel a bit like navigating a maze of version conflicts and system dependencies. By using tools like pyenv and pyenv-virtualenv, you can streamline the process and avoid common pitfalls. In this guide, we’ll walk through setting up Python with Homebrew and Pyenv, with explanations of why each step is important and what’s happening under the hood.

Let’s get started.

---

Why Use Pyenv?

You might wonder why tools like pyenv are necessary when macOS already comes with Python pre-installed. Here’s the deal:

• System Dependency Issues: The version of Python included with macOS is often used by the operating system itself. Changing or upgrading it can lead to unintended issues.
• Multiple Versions: Different projects may require different Python versions. For example, one project might need Python 3.9, while another requires Python 3.13. Pyenv makes it easy to switch between them.
• Environment Isolation: Pyenv supports creating virtual environments, ensuring project dependencies don’t conflict.

In short, Pyenv helps you maintain control and flexibility in your Python setup.

---

Installing Pyenv

Step 1: Install Homebrew

Homebrew is a package manager for macOS that simplifies the installation of software. Check out my post here. Don’t worry. I’ll wait.

Step 2: Install Pyenv

With Homebrew installed, adding Pyenv is straightforward:

brew install pyenv

Then, configure your shell to initialize Pyenv. Add the following lines to your shell profile (~/.zshrc, ~/.bashrc, or similar):

eval "$(pyenv init --path)"
eval "$(pyenv init -)"

Reload your shell profile to apply these changes:

source ~/.zshrc

Finally, verify that Pyenv is installed:

pyenv --version

---

Using Pyenv to Manage Python Versions

Install a Specific Version of Python

Let’s install Python 3.13.0 for a project. Pyenv downloads and compiles the requested version, so this step may take a few minutes:

pyenv install 3.13.0

To see all installed versions:

pyenv versions

Set a Global Python Version

If you want Python 3.13.0 to be your default version for all projects, set it globally:

pyenv global 3.13.0

This updates Pyenv’s global configuration, which affects all directories unless overridden.

Set a Local Python Version

To tie a specific Python version to a project, navigate to the project directory and set a local version:

pyenv local 3.13.0

This creates a .python-version file in the directory, specifying which Python version to use whenever you’re working in that folder. You can view the file’s contents with:

cat .python-version

---

Managing Virtual Environments

Step 1: Install pyenv-virtualenv

The pyenv-virtualenv plugin enhances Pyenv by adding virtual environment management. Install it with:

brew install pyenv-virtualenv

Add the following initialization line to your shell profile:

eval "$(pyenv virtualenv-init -)"

Reload your shell profile:

source ~/.zshrc

Step 2: Create a Virtual Environment

Creating a virtual environment is simple:

pyenv virtualenv 3.13.0 my-project-env

This sets up a new environment using Python 3.13.0.

Step 3: Viewing Virtual Environments

To list all virtual environments, run:

pyenv virtualenvs

This command provides an overview of all environments and their associated Python versions.

Step 4: Auto Activation

To ensure the environment activates automatically when you enter your project directory, set it as the local environment:

pyenv local 3.13.0/envs/my-project-env

The .python-version file will now include both the Python version and the virtual environment. This seamless workflow eliminates manual activation steps.

---

Verifying Installation with a Basic Example

Let’s confirm everything is set up correctly. To confirm your setup, open a terminal and start a Python shell by typing python. Once inside the shell, run the following code to verify your installation:

# Simple Python example to test installation
import sys
print(f"Python version: {sys.version}")

# Test a library
import math
print(f"The square root of 16 is {math.sqrt(16)}")

You should see output similar to:

Python version: 3.13.0 (default, ...)
The square root of 16 is 4.0

Type quit() to exit the Python shell.

---

Wrapping Up

By following this guide, you’ve set up Python with Pyenv and Pyenv-Virtualenv on macOS, giving you a flexible, reliable development environment. Whether you’re tackling web development, automation, or data science, these tools will keep your projects running smoothly.

Let’s keep building!