Setting Up the Development Environment on macOS

This guide describes the process to setup a development environment for contributing to colour-science projects on macOS. It is by no means prescriptive, and not every step is required. The guide assumes Homebrew as the package manager and Visual Studio Code as the IDE / text editor.

Additionally, the installation of complex dependencies such as OpenImageIO and PyGraphviz is described.

It was contributed by @tjdcs and last updated on the 2024-01-28.


Install Homebrew:

/bin/bash -c "$(curl -fsSL"

Install the required Python versions:

brew install python@3.9 python@3.10 python@3.11 python@3.12


(Re)Install Poetry:

Poetry used to introduce breaking changes to the installer between minor versions, it is thus recommended to reinstall it.

curl -sSL | python3 - --uninstall
curl -sSL | python3 -

graphviz and OpenImageIO

Using Homebrew:

brew install graphviz OpenImageIO

Then append the following exports to your shell dotfile, e.g. ~/.zshrc:

export LIBRARY_PATH=$LIBRARY_PATH:$(brew --prefix graphviz)/lib/
export CPATH=$CPATH:$(brew --prefix graphviz)/include/
export PYTHONPATH=$PYTHONPATH:$(brew --prefix OpenImageIO)/lib/python3.12/site-packages/OpenImageIO/

Cloning colour's Repository

First, fork the colour repository, making sure to set or replace the environment variables in these commands.

git clone$GITHUB_USER/colour.git
cd colour

Working with Visual Studio Code from the Terminal

The following step is optional, but helpful to store Poetry's virtual environment into colour's directory.

poetry config true

Install the poetry environment

poetry env use 3.12
poetry install --all-extras

Opening Visual Studio Code

In colour's directory, issue the following command to launch Visual Studio Code:

code .

If the code command is not available in your shell environment, open up Visual Studio Code from the Applications folder, press Cmd + Shift + P to bring up the Command Palette, then type Shell Command: Install 'code' command in PATH and press enter.

Running the Unit Tests / Preflight

colour uses the invoke framework to expose several useful preflight commands:

poetry shell
invoke formatting && invoke quality && invoke precommit && invoke tests

or if you just want to run the tests, including the doctests:

invoke tests

CTL (Optional)

colour provides a wrapper to the AMPAS Color Transformation Language (CTL) If you want to be able to fully build and contribute to this part of the codebase, it needs to be installed. Unfortunately, the version currently provided by Homebrew does not appear to work on the latest macOS and the relevant environments, thus, it must be installed from source at the moment:

brew install cmake ilmBase openexr libtiff aces_container

git clone

cd CTL
mkdir build && cd build

cmake .. -J 10
sudo make install

See Also

Please refer to the contributing guide for more information about the contributing process.