Mayan EDMS stores documents in their original file format only changing the filename to avoid collision.

File storage

The files are stored and placed under Mayan EDMS “control” to avoid filename clashes each file gets renamed to its UUID (Universally Unique ID), without extension, and stored in a simple flat arrangement in a directory.

blockdiag mayan_1-1.pdf mayan/media/document_storage/ab6c1cfe-8a8f-4a30-96c9-f54f606b9248 upload

This doesn’t stop access to the files but renaming, moving or updating directly them is not recommended because it would throw the database out of sync.

Because Mayan EDMS components are as decoupled from each other as possible, storage in this case is decoupled and its behavior is controlled not by the project but by the Storage module class. All the other modules don’t make any assumptions about how the actual document files are stored. This way files can be saved locally, over the network or even across the Internet and everything will still operate exactly the same.

The default file storage backend: storage.backends.filebasedstorage.FileBasedStorage is a simple backend that only supports paths and not IP addresses. In case you are interested in using remote volumes to store documents (NFS, SAMBA), first mount these volumes so that they appear as a directories to Mayan EDMS. For direct support for remote volumes a custom backend would be needed such as those provided by the Django Storages project (

Object storage

It is possible to use object storage instead of the default filesystem based storage. One such object storage system is Amazon S3 (Simple Storage Service) API compatible object storage. The following steps will configure Mayan EDMS to use a S3 style storage for documents.

  1. Install the django-storages and boto3 Python libraries.
  • For the direct deployment method of installation use:

    pip install django-storages boto3
  • or if using the Docker image, add the following the command line that runs the container:

    -e MAYAN_PIP_INSTALLS='django-storages boto3'
  1. From the web interface navigate to the System ‣ Setup ‣ Setting ‣ Documents menu.

  2. Locate the DOCUMENTS_STORAGE_BACKEND setting, press Edit and enter:

  3. Save and locate the setting DOCUMENTS_STORAGE_BACKEND_ARGUMENTS, press Edit and enter:

    '{access_key: <your S3 access key>, secret_key: <your S3 secret key>, bucket_name: <S3 bucket name>}'
  4. Save and restart your Mayan EDMS installation for the setting to take effect.


Mayan EDMS stores documents in their original file format only changing the filename to avoid collision. For best input and output speed use a block based local filesystem for the /media sub folder of the path specified by the MEDIA_ROOT setting. For increased storage capacity use an object storage filesystem like S3.

To use a S3 compatible object storage do the following:

  • Install the Python packages django-storages and boto3:

    • Using Python:

      pip install django-storages boto3
    • Using Docker:

      -e MAYAN_PIP_INSTALLS='django-storages boto3'

On the Mayan EDMS user interface, go to System, Setup, Settings, Documents and change the following setting:

  • DOCUMENTS_STORAGE_BACKEND to storages.backends.s3boto3.S3Boto3Storage
  • DOCUMENTS_STORAGE_BACKEND_ARGUMENTS to '{access_key: <your access key>, secret_key: <your secret key>, bucket_name: <bucket name>}'.

Restart Mayan EDMS for the changes to take effect.