Mayan EDMS can be configure using various methods.

Via environment variables

  1. Go to the System ‣ Setup ‣ Indexes menu.

  2. Create a new index using Actions > Create new.

To use environment variables, lookup the name of the setting you want to override in the System ‣ Setup ‣ Settings menu. To pass a value via an environment variable append "MAYAN_" to the name of the settings option. For example, to change the number of documents displayed per page (COMMON_PAGINATE_BY, by default 40), use:


Restart Mayan EDMS and the new value will take effect. The Settings menu can be used to verify if the overridden setting value is being interpreted correctly.

Via YAML configuration file

Added in version 3.1.

It is possible to modify the different settings by creating or editing the media/config.yml file. This file is formatted in the YAML markup language ( Here is an example of what the looks like:

EMAIL_BACKEND: django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST: localhost
HOME_VIEW: common:home

Every time Mayan EDMS is able to start correctly it will copy the config.yml and create a backup copy in the same directory named config_backup.yml. This file is used to revert to the last know configuration file known to be valid. You can revert manually by copy the file or by using the revertsettings management command from the command line.

Via Python settings files

Another way to configure Mayan EDMS and the one required when more extensive setup is required (such as when using external Python libraries), is via Python-style, settings files. A folder named user_settings/ is created for the purpose of hosting these settings files.

Create a file with any valid name and a .py extension in the user_settings/ folder. The file must starts with a global import of mayan.settings.production. In the form:

from mayan.settings.production import *

Now add the corresponding lines to override the default settings. In the settings file, it is not necessary to prepend the string MAYAN_ to the setting option. For example, to change the number of documents displayed per page (COMMON_PAGINATE_BY, by default 40), use:




when using the environment variable method.

For this example let’s assume the file was saved with the name

The way used to tell Mayan EDMS to import this file will vary based on the installation method.

For the Docker installation method, the full import path will be user_settings.mysettings and can only be passed via the MAYAN_SETTINGS_MODULE environment variable like this:

docker run <...> -e MAYAN_SETTINGS_MODULE=user_settings.mysettings


The settings files must be valid Python modules. Errors in the Python settings files might prevent Mayan EDMS for starting properly. Errors other than syntax errors, might cause Mayan EDMS to starting up in an incomplete manner making debugging difficult.

Setting priority

The settings will be applied in the following order:

  1. YAML configuration file.

  2. Python settings file.

  3. Environment variables.

Only settings overridden via environment variables will be identified as such in the settings view.

Settings overridden or set via Python settings files will not be identified as such in the settings view.