Python Setup for macOS

Let's setup Python with the latest and greatest tools for your macOS developer environment! Many folks seem to still be installing Python from the download links on the website and installing dependencies with requirements.txt.

TLDR:

xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install pyenv
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
pyenv install 3.12.1
pyenv global 3.12.1
pip install --upgrade pip
pip install poetry
poetry init
poetry shell

Definitions

• Python: https://www.python.org Python is an interpreted, high-level and general-purpose programming language.
• C: https://en.wikipedia.org/wiki/C_(programming_language) a widely used lower level programming langauage.
• CPython: https://en.wikipedia.org/wiki/CPython is the reference implementation of the Python programming language. Written in C and Python, CPython is the default and most widely used implementation of the Python language.
• Xcode: https://developer.apple.com/xcode/ this is the IDE for macOS and iOS development.
• xcode-select: https://developer.apple.com/library/archive/technotes/tn2339/_index.html this is a tool that installs the minimal dependencies from Xcode to do C style development on macOS.
• Homebrew: http://brew.sh this is a third party package manager for macOS and Linux.
• pip: https://pip.pypa.io/en/stable/ pip is the package installer for Python.
• Virtual Environments (virtualenv): https://docs.python.org/3/tutorial/venv.html Virtual environments are a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them.
• Pyenv: https://github.com/pyenv/pyenv Pyenv is a Python version manager. It lets you install and switch between different versions of Python quickly.
• pyproject.toml: https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/ This is the standard for Python project management. It holds your project's metadata, dependencies, and build tooling config.
• Poetry: https://python-poetry.org Poetry is a tool to manage your Python projects, dependencies and build piplines

1. Building C and C Libraries with xcode-select

The first thing we need to do is setup the C dependencies for macOS. We'll need to use the tool xcode-select. This tool installs the minimal dependencies from Xcode to do C style development on macOS. CPython (the standard Python you'll be using, there are others!) relies on having specific macOS C dependencies which xcode-select will install on your system.

Install via:

xcode-select --install

2. Install Homebrew

Homebrew is the most widely used 3rd party package manager for macOS and we'll use this to install and manage external tools!

Install via:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Pyenv

Remember, the Python installed on macOS is not the most up to date and will even be removed in future macOS releases!

You'll use Pyenv to install the latest and greatest version of Python and set that to your system default.

Install via:

brew install pyenv

Then setup pyenv to work with zsh:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc

Install Python:

pyenv install 3.12.1

Set the new version as your System Default:

pyenv global 3.12.1

Verify the install with:

python --version
> Python 3.12.1

Python makes use of a package manager called pip. This can install tools for your system or dependencies when building your projects! Many Python Packages are hosted on PyPi. Other packages can come from Git repostiories or your local filesystem.

Verify you have the latest and greatest pip:

pip install --upgrade pip

4. Poetry

https://python-poetry.org

You may remember using requirements.txt and setup.py. These were the old ways of managing Python project's. Those tools are a thing of the past (and have been since May 2016!!!!). The old way of managing dependencies lead to many mismatched versions betweened developers own machines and production. Lockfiles were introduced to solve this problem in many ecosystems, and the Python community had to create 3rd party tools to create these. Lock files pin the exact versions of dependencies used in your project. This means that when you install dependencies, you will get the exact same versions as your teammates and have consistent production builds.

Today we use pyproject.toml to know what Python dependencies our project relies on. Read more about pyproject.toml here.

Poetry is a tool to manage your Python projects. Together with pyproject.toml, Poetry handles creation of virtualenv's, installing production and development deps, create poetry.lock files, hold package info, build and push packages, and hold tooling config. It feels very similar to how npm, package.json, and package-lock.json work for Node based projects!

There are a few ways to install Poetry but we will actually install it to the currently installed Python version's global pip packages!

Install poetry via:

pip install poetry

5. Setup a new Python project

Now that your system is configured to do development with Python, let's make a new project!

mkdir your-project && cd your-project
git init
poetry init
poetry add Django (add a new prod dep)
poetry add --group=dev ruff (add a dev dep)
poetry shell (this is activating the virtualenv made by poetry!)

Now get to building!

Extra Credit: No More Virtualenv:

For times you want to make a virtual environment not managed by Poetry, remember it comes bundled into Python! And you have the latest Python! The command virtualenv is no longer required for use or to install.

Please create virtualenv's via:

# we'd prefer you name them .venv
python -m venv .venv
 
# or name them whatever you'd like
python -m venv <name of your venv>