Setting up a development environment

These instructions will describe how to set up a development environment for the Numbas runtime and editor.


Create a directory named numbas, which you’ll use to store all the git repositories and other files associated with the development environment.

You’ll need Python 3.8 or later and the version control tool git.


  1. Install Python 3 from

  2. Install Git for Windows.

  3. Install GNU make. One way of doing this is through the chocolatey package manager.

    make is also included with Cygwin.


  1. Install Git and Python 3 using the packaging system:

    $ apt install git python3


Python 3 is pre-installed on MacOS.

Most versions of MacOS also have git pre-installed. If not, it’s included with XCode, or you can follow the instructions at

Set up a Python virtual environment

It’s a good idea to use a Python virtual environment during development work, to avoid conflicts with any other projects you’re working on.

If you don’t already have the virtualenv package installed, install it:

$ pip3 install virtualenv

Then, create a virtual environment:

$ virtualenv -p python3 numbas_venv

To activate it on Linux or Mac:

$ source numbas_venv/bin/activate

To activate it on Windows:

> numbas_venv\Scripts\activate

You’ll need to activate the virtual environment each time you open a new terminal.

Clone the repositories

  1. The Numbas runtime compiler:

    $ git clone compiler
  2. The Numbas editor:

    git clone editor

Install required Python packages

Both the compiler and editor have lists of packages that they require. There is a separate file listing packages required to build the editor documentation.

Install all of these:

$ pip3 install -r editor/requirements.txt
$ pip3 install -r editor/requirements-docs.txt
$ pip3 install -r compiler/requirements.txt

Set up the editor

Run the “first setup” script:

$ cd editor
$ python

This will configure the editor based on your answers to a few questions, and write the file numbas/

Answer Y to the first question, “Is this installation for development?”, and then enter details for your admin account.

If you make any mistakes, you can run the script again, or edit numbas/ directly.

Run the editor server

The editor is a Django app.

There is a script called which provides a variety of tools, including a development server.


$ python runserver

Open http://localhost:8000 in your web browser.

The editor should now be usable: try creating a question and running it.