Umar Mahmud

Setting Up a Python Development Environment for macOS

Note: This guide uses macOS 13 or higher, the zsh shell and the brew package manager

A working Python installation will include a Python interpreter as well as associated Python libraries. On macOS, there is a system installation of Python that must NOT be modified or removed. This installation is located at /System/Library/Frameworks/Python.framework with a symlink in /usr/bin/python.

DO NOT use the system Python (sometimes referred to as "default Python") for Python development. Instead, install your own version of Python. The best way to install and manage your own Python versions is through pyenv.

Installing pyenv #

I prefer to install pyenv using brew.

brew install pyenv

Next, add pyenv to your shell environment (zsh).

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

Restart your shell.

exec "$SHELL"

Install your desired version of Python.

pyenv install <version>

Set your installed version as the global default.

pyenv global <version>

Installing Packages #

When installing packages, make a habit of using the -m flag to make sure you are using the correct python interpreter with pip:

python -m pip install <package-name>

When using pyenv, pip should install packages in the Python installation’s own site-packages folder, different from the system’s site-packages folder. Example directory that pyenv will use (version set as 3.8.10):

/Users/umar/.pyenv/versions/3.8.10/lib/python3.8/site-packages

Working with Virtual Environments #

Usually, you will not want to install packages directly into your site-packages directory. Instead, you will want to create virtual environments for your specific projects. This is natural since each project will likely have different dependecies associated with it.

pyenv-virtualenv is a pyenv plugin that makes it easy to create virtual environments. Install with brew:

brew install pyenv-virtualenv

Append your .zshrc file with the following and then restart your current shell session.

eval "$(pyenv virtualenv-init -)"

Create a virtual environment.

pyenv virtualenv <version> <environment-name>

Activation of the newly created environment should be done locally in your project directory. cd to your directory and activate the newly created environment:

pyenv local <environnment-name>

Confirm the activation with pyenv which python and you should see something like: /Users/umar/.pyenv/versions/<environment-name>/bin/python.

Activation of a virtual environment with pyenv-virtualenv will create a .python-version file in your project. If you are using git, it is a good idea to gitignore this file.

Now, any necessary package(s) for the environment can be installed.

pip install <package-name>

As soon as you cd out of your project folder, the virtual environment will become deactivated.

Next time you need to activate your virtual environment, simply cd-ing into the project folder should do it.

Using Virtual Environments with Jupyter Notebooks #

Virtual environments can be created and added to Jupyter Notebooks as kernels.

To configure a virtual environment for Jupyter, first navigate to the folder for your notebook. Next, create a virtual environment with pyenv and activate it locally in your folder.

Then, inside your virtual environment, install the ipykernel package with pip and run

ipython kernel install --user --name <environment-name>

You are free to deactivate the virtual environment now. Of course you must activate it again (simply cd-ing to the notebook folder should accomplish this) to install any additional packages.

Start the server on localhost with

python -m jupyterlab

You should now see the newly added kernel in the user interface.

Useful commands #

python -m site shows the location of the packages folder(s)

pip list shows ALL installed packages, whether or not they were installed using pip

pip freeze shows all packages installed using pip

pip show <package-name> shows package info, including location

pyenv versions shows all Python versions with current version starred

pyenv virtualenvs list existing virtual environments

pyenv uninstall <environment-name> delete a virtual environment

jupyter kernelspec list list all kernels in jupyter

jupyter kernelspec uninstall kernel remove kernel from jupyter