Skip to content


System dependencies⚓︎

uMap is built with the Python language, and the Django framework. It needs a PostgreSQL database, with the Postgis extension enabled.

Here are the commands to install the required system dependencies.

sudo apt update
sudo apt install python3 python3-dev python3-venv virtualenv postgresql gcc postgis libpq-dev
yay postgis extra/postgresql-libs
brew install postgis
sudo dnf install postgis libpq-devel make gcc python3-devel


Depending on your system, you might need to create a postgres user, the database, and initialize postgres. Here's how:

createuser umap -U postgres
createdb umap -O umap -U postgres
psql umap -c "CREATE EXTENSION postgis" -Upostgres

Getting started⚓︎

Create a geo aware database. See the GeoDjango docs for backend installation.

Creating a virtual environment⚓︎

It is recommended to install python projects in a virtual environment to avoid mixing the project installation with your system dependencies. But it's not a requirement and it is up to you 🫣

python -m venv venv
source venv/bin/activate

Installing the dependencies⚓︎

You can get all the project dependencies installed with the following command:

pip install umap-project


Create a default file, that you will modify with your setting.

wget -O

Reference it as env var:

export UMAP_SETTINGS=`pwd`/

Add database connection information in, for example
    'default': {
        'ENGINE': 'django.contrib.gis.db.backends.postgis',
        'NAME': 'umap',

Depending on your installation, you might need to change the user that connects the database.

It should look like this:
    "default": {
        "ENGINE": "django.contrib.gis.db.backends.postgis",
        "NAME": "umap",
        "USER": "postgres",

Add a SECRET_KEY in with a long random secret key
SECRET_KEY = "a long and random secret key that must not be shared"

You can easily generate one with openssl:

openssl rand -base64 32

uMap uses python-social-auth for user authentication. So you will need to configure it according to your needs. For example

Example of callback URL to use for setting up OAuth apps

Adapt the STATIC_ROOT and MEDIA_ROOT to your local environment.

Bootstrapping the database⚓︎

Here are the commands you'll need to run to create the tables, collect the static files, etc.

# Create the database tables
umap migrate

# Collect static files
umap collectstatic

# Create a super user
umap createsuperuser

# Finally start the server
umap runserver

Configuring emails⚓︎

UMap can send the anonymous edit link by email. For this to work, you need to add email specific settings. See the related settings for more info.

Upgrading your installation⚓︎

Usually, for upgrading, you need those steps:

pip install umap-project --upgrade
umap migrate
umap collectstatic