Skip to content

Development setup

This page lists the steps required to start developing Gramps Web API. It will be assumed that you are using Ubuntu Linux.

Python version

The Web API requires Python 3.7 or newer.

Install Gramps

The Web API requires the Gramps Python library to be importable. Starting from Gramps 5.2.0, it will be installable via pip. Right now, development is still based on Gramps 5.1.x, so the most convenient option is to install the Gramps apt package on Ubuntu

sudo apt install gramps


Note that using the gramps Python package from Gramps installed with apt requires using the system Python interpreter, so you cannot work in a virtual environment.

Clone the Web API repository

Clone the Web API to your PC (assuming you have set up an SSH key with Github) using

git clone
cd gramps-web-api

Install prerequisites

To start development, please install the dependencies by running

pip3 install -r requirements-dev.txt

Install the library in editable mode


pip3 install -e . --user

Set up pre-commit hooks

To set up the pre-commit hooks for the repository, run

pre-commit install
in the repository root. This will e.g. make sure that all source files are nicely formatted with black.

Run tests

To run the unit tests, run

in the repository root.

Generate a configuration file

Example content:

TREE="My Family Tree"


Do not use this configuration in production.

See Configuration for a full list of config options.


Do not use your production database for development, but use a copy of it or the Gramps example database.

Add users

You can add a user with owner permissions by running

python3 -m gramps_webapi --config path/to/config user add owner owner --role 4
This uses username and password owner.

Run the app in development mode


python3 -m gramps_webapi --config path/to/config run
The API will be accesible at by default, which displays an empty page. Access your Gramps data using the API described by For example, to show people go to

To choose a different port, add the --port option.