An Opinionated Python Setup Guide for Mac

TLDR: Use the pyenv distribution from homebrew. Never use the system version of Python. Never use the base pip environment. For individual projects, default to Pipenv, although Poetry or venv are very reasonable alternatives. Opt for builtin relative path dependencies instead of modifying $PYTHONPATH. Using conda for specific projects is fine, but it is vital to turn off base auto-activation.

Python environments are classically terrible:

Source: xkcd, real life

They don’t have to be. Here’s my Python setup that I’ve used for years and years and hasn’t screwed me over yet:

Step 1: Install Homebrew

Homebrew is a package manager for MacOS. It’s pretty standard, so if you’re doing dev work on a Mac, you’ll run into it sooner or later.

Homebrew installation instructions here

Step 2: Install pyenv using brew

Once you’ve got Homebrew installed, install pyenv. Pyenv is a project that helps make managing and updating your Python installation somewhat reasonable. It allows you to maintain multiple versions of Python and upgrade with almost no effort. It’s not perfect, but it’s leagues above anything else I’ve used.

Pyenv installation instructions here

Once you’ve installed pyenv, make sure to restart your shell and continue onto the next step.

Step 3: Install python (for real this time)

After installing pyenv, you can install the latest version of Python via the following.

# If you're reading in the future, change the version to suit the latest
# stable version of Python.

pyenv install 3.11 # Downloads and installs latest py 3.11.
pyenv global 3.11 # Sets the system to use the newly downloaded version.

Once the above are done, you can verify your python install via the following commands.

which python
# Should print: /Users/evinsellin/.pyenv/shims/python

python --version
# Should print: Python 3.11.1 

If you run into issues, make sure to restart your terminal.

Step 4: Install Pipenv. Default to using Pipenv for new projects

Pipenv is one of the many tools for managing virtual environments in python. It’s very well established, and provides some nice features on top of raw venv management that they’ll be very happy to tell you about.

Pipenv installation instructions here.

The most important thing in this category isn’t the specific virtual environment manager. I’ve used both venv and Poetry to great effect. The important thing is that you always use a virtual environment, for every project you do.

(Note: In previous versions, I opted for recommending Poetry above Pipenv, but it seems likely that Poetry isn’t going to have the same industry buy-in that Pipenv currently enjoys.)

Step 5 (if you need it): Install Anaconda; instantly configure it to not activate base.

If you don’t know that you have a burning use case for Anaconda, you can skip this step.

Anaconda is a combination package manager and environment for Python and R largely used in data science. It can be invaluable for managing specific projects, like those that rely on hard-to-install packages like OpenCV. For non data science applications, though, it can prove mostly redundant.

Anaconda setup is where a lot of python setups can go awry, as conda likes shimming Python similar to what pyenv does. However, if you don’t activate base by default, the two can coexist quite peacefully.

Anaconda installation for Mac here

Once you’ve got conda installed, you can configure it to not activate base using the following command:

conda config --set auto_activate_base false

If you’re doing a specific project that requires conda, you can very easily reactivate it for a single session by running the following:

conda activate

Step 6: Continued vigilance

That’s it! You should have a nice, easy to use Python environment! Yay!

However, Python environments have a tendency to decay over time. Often new projects have nuances that require small changes to your Python environment, such as depending on a specific Python version, or requiring a dependency based on a relative path. These changes will pile up over time, and if you’re not careful, it’ll make your environmental setup very complicated, a la xkcd.

Under this environment, do the following to hold off the chaos as long as possible:

• Use pyenv as your manager for all Python binaries.
• Never use system Python (e.g. /usr/bin/python3).
• Upgrade python with brew update && pyenv install [version] && python global [version]
• Never manually modify $PATH for Python purposes.
• Use pypi for as your package repository almost exclusively.
• Never use $PYTHONPATH. Instead, opt for builtin dependency resolution methods in Pipenv or Poetry.
• Rarely (or never) pip install anything outside of a virtual environment.
• Feel free to use conda but keep it scoped to individual projects rather than as a system-wide configuration.

This article was written in like half an hour for a friend. If it doesn’t work for you, leave a comment and we’ll improve it!