Python Development Environment on MacOS Ventura and MontereyLast updated: February 02, 2023
While installing Python and Virtualenv on MacOS Ventura and Monterey can be done several ways, this tutorial will guide you through the process of configuring a stock Mac system into a solid Python development environment.
This guide assumes that you have already installed Homebrew. For details, please follow the steps in the MacOS Configuration Guide.
We are going to install the latest version of Python via asdf and its Python plugin. Why bother, you ask, when Apple includes Python along with MacOS? Here are some reasons:
- When using the bundled Python, MacOS updates can remove your Python packages, forcing you to re-install them.
- As new versions of Python are released, the Python bundled with MacOS will become out-of-date. Building Python via asdf means you always have access to the most recent Python version.
- Apple has made significant changes to its bundled Python, potentially resulting in hidden bugs.
- Building Python via asdf includes the latest versions of Pip and Setuptools (Python package management tools)
Use the following command to install asdf and Python build dependencies via Homebrew:
brew install asdf openssl readline sqlite3 xz zlib
# Load asdf for this session
source (brew --prefix)/opt/asdf/asdf.fish
# Ensure asdf loads for all subsequent sessions
echo source (brew --prefix)/opt/asdf/asdf.fish >> ~/.config/fish/config.fish
# Ensure asdf doesn’t disrupt activated virtual environments
echo 'if set -q VIRTUAL_ENV; source "$VIRTUAL_ENV/bin/activate.fish"; end' >> ~/.config/fish/config.fish
For Zsh (the default shell on MacOS):
. $(brew --prefix asdf)/asdf.sh
echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ~/.zshrc
Install the asdf Python plugin and the latest version of Python:
asdf plugin add python
asdf install python latest
Note the Python version number that was just installed. For the purpose of this guide, we will assume version 3.11.1, so replace that number below with the version number you actually just installed.
Set the default global Python version:
asdf global python 3.11.1
Confirm the Python version matches the latest version we just installed:
Let’s say you want to install a Python package, such as the Virtualenv environment isolation tool. While many Python-related articles for MacOS tell the reader to install Virtualenv via
sudo pip install virtualenv, the downsides of this method include:
- installs with root permissions
- installs into the system /Library
- yields a less reliable environment when using Python built with asdf
As you might have guessed by now, we are going to use the asdf Python plugin to install the Python packages that we want to be globally available. When installing via
python -m pip […], packages will be installed to:
First, let’s ensure we are using the latest version of Pip and Setuptools:
python -m pip install --upgrade pip setuptools
In the next section, we’ll use Pip to install our first globally-available Python package.
Python packages installed via Pip are global in the sense that they are available across all of your projects. That can be convenient at times, but it can also create problems. For example, sometimes one project needs the latest version of Django, while another project needs an older Django version to retain compatibility with a critical third-party extension. This is one of many use cases that Virtualenv was designed to solve. On my systems, only a handful of general-purpose Python packages (including Virtualenv) are globally available — every other package is confined to virtual environments.
With that explanation behind us, let’s install Virtualenv:
python -m pip install virtualenv
asdf reshim python
Create some directories to store our projects, virtual environments, and Pip configuration file, respectively:
mkdir -p ~/Projects ~/Virtualenvs ~/.config/pip
We’ll then open Pip’s configuration file (which may be created if it doesn’t exist yet)…
… and add some lines to it:
require-virtualenv = true
require-virtualenv = true
Now we have Virtualenv installed and ready to create new virtual environments, which we will store in
~/Virtualenvs. New virtual environments can be created via:
If you have both Python 3.10.x and 3.11.x installed and want to create a Python 3.10.9 virtual environment:
virtualenv -p ~/.asdf/installs/python/3.10.9/bin/python project-b
Restricting Pip to virtual environments
What happens if we think we are working in an active virtual environment, but there actually is no virtual environment active, and we install something via
python -m pip install foobar? Well, in that case the
foobar package gets installed into our global site-packages, defeating the purpose of our virtual environment isolation.
Thankfully, Pip has an undocumented setting (source) that tells it to bail out if there is no active virtual environment, which is exactly what we want. In fact, we’ve already set that above, via the
require-virtualenv = true directive in Pip’s configuration file. For example, let’s see what happens when we try to install a package in the absence of an activated virtual environment:
python -m pip install markdown
Could not find an activated virtualenv (required).
Perfect! But once that option is set, how do we install or upgrade a global package? We can temporarily turn off this restriction by defining a new function in
PIP_REQUIRE_VIRTUALENV="0" python -m pip "$@"
(As usual, after adding the above you must run
source ~/.zshrc for the change to take effect.)
If in the future we want to upgrade our global packages, the above function enables us to do so via:
gpip install --upgrade pip setuptools virtualenv
You could achieve the same effect via
PIP_REQUIRE_VIRTUALENV="0" python -m pip install --upgrade […], but that’s much more cumbersome to type every time.
Creating virtual environments
Let’s create a virtual environment for Pelican, a Python-based static site generator:
Change to the new environment and activate it via:
To install Pelican into the virtual environment, we’ll use Pip:
python -m pip install pelican markdown
For more information about virtual environments, read the Virtualenv docs.
These are obviously just the basic steps to getting a Python development environment configured. Feel free to also check out my dotfiles.
If you found this article to be useful, feel free to find me on Twitter.