Setting up a development environment#

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

The editor is a Django app.


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 starts a web-based setup interface where you can configure the editor’s settings.

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

The web-based setup interface.

Tick Is this installation for development?, fill in the Path of the Numbas compiler field and the superuser details. Then click Save.

Once the setup jobs have finished, go back to the terminal and end the setup script (normally Ctrl-C does it)).

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

Run the editor server#

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.