Setting Up and Using the Development Environment#
Last revised on 2026 MAY 28 by Z. Ellis.
Note
The following covers setting up a development environment for Scarabaeus. If you are simply using Scarabaeus, see the User Guide.
Developers on the Scarabaeus team use a few more tools in addition to those included in the distributed package to support running tests, generating documentation, writing tutorials, and compiling source code. This document will guide a developer through setting up the development environment necessary for these tasks.
Prerequisites#
Most of the development team uses VSCode as their IDE because of its extension ecosystem. Below are the recommended extensions for development:
Python: provides language support for Python
Rust Analyzer: provides language support for Rust
GitLens: most of the development team uses GitLens for managing version control
Jupyter: SCB utilizes Jupyter Notebooks for all tutorials
Clone the Repository#
Clone the Scarabaeus repository.
git clone <https://github.com/CCAR-ORCCA/scarabaeus>
cd scarabaeus
Set Up A Virtual Environment#
Before installing the developer environment, we’ll need to create a virtual environment to place hold it. In your terminal, run:
python3 -m venv .venv
And activate it with:
source .venv/bin/activate
.venv\Scripts\activate
You’ll know it’s activated when you see (.venv) in your terminal. To deactivate, run:
deactivate
Install the Development Environment#
With the virtual environment activated, run the following command to install the development environment:
pip install -e . --group dev
Note
Sometimes pip might not recognize the --group command. This is usually fixed by updating with python -m pip install --upgrade pip
This will install more dependencies than the standard installation, which include:
maturin: build Rust code and bind it to Python
pre-commit: manage Scarabaeus Git hooks
nbstripout: remove cell results from Jupyter Notebooks when pushing to Git
numpydoc: formatting for documentation generation
pytest: testing suite architecture
The following sections require the packages installed with the dev environment to function.
Build From Source#
See Building From Source.
Enable Git Commit Hooks#
The first time you clone the repository or create/pull a new branch, in the terminal run:
pre-commit install
This will add Scarabaeus’ development hooks to your Git configuration, acting as an extra layer of quality assurance when you push a commit. If the pre-commit command is not found, ensure that you’ve installed the [Scarabaeus dev environment](#set-up-scarabaeus-dev-environment).
The hooks we use are:
nbstripout: Jupyter Notebooks are a powerful tool for writing tutorials, but they also produce metadata in their cells when run that we don’t want to track on git. We use nbstripout to automate this removal.