Back to Top

Installing Mayan on MacOSX

Mayan EDMS supports various different packages to enable the full functionality of Mayan. This guide helps with the installation and configuration of Mayan on MacOSX and may vary between different installations.

In my configuration, I am using homebrew to install the required unix utilities that are being used by Mayan. Other environments can also be used.

Homebrew can be found at:

MacOSX Requirements

XCode and XCode command line utilities will be required to build the different utilities needed for Homebrew and for Mayan.

XQuartz is also needed to build some of the libraries and tools. When installing XQuartz it installs in /opt. This is not a default build path for XCode, so type this before running the commands in your shell: 

export CPPFLAGS=-I/opt/X11/include

Python Requirements

The following is the basic python requirements that need to be installed for Mayan to work on MacOSX.

Python - I am using Python 2.7.5
Django – A high-level Python Web framework that encourages rapid development and clean, pragmatic design.
django-filetransfers – File upload/download abstraction
django-mptt – Utilities for implementing a modified pre-order traversal tree in django
django-taggit – Simple tagging for django
 – The simplest way to extract text from PDFs in Python

Tool Requirements

The following is the utilities/tools that need to be installed to add functionalities needed by Mayan to operate properly.

tesseract-ocr – An OCR Engine that was developed at HP Labs between 1985 and 1995… and now at Google.
unpaper – post-processing scanned and photocopied book pages
gpg – The GNU Privacy Guard

Optional requirements

To store documents in a GridFS database
PyMongo – the recommended way to work with MongoDB from Python
GridFS – a storage specification for large objects in MongoDB
MongoDB – a scalable, open source, document-oriented database

Enhanced MIME detection
libmagic – MIME detection library, if not installed Mayan EDMS will fall back to using python’s simpler mimetype built in library
python-magic – A python wrapper for libmagic

Image conversion backends
Mayan EDMS has the ability to switch between different image conversion backends, at the moment these three are supported:

ImageMagick – Convert, Edit, Or Compose Bitmap Images. If you are going to install ImageMagick using brew, please ensure that you install all the correct image libraries before installing ImageMagick, such as libtiff, libjpeg etc.
GraphicMagick – Robust collection of tools and libraries to read, write, and manipulate an image.
Python only – Relies on PIL to support a limited set of the most common graphics formats.
By default the python backend is used.



The following assumptions are made for the installation instructions below:

  1. Python is installed and configured
  2. MySQL or PostgresQL is configured for the database backed
  3. Homebrew is installed and configured
  4. Python easy_install is setup and configured within python
  5. Python virtualenv is setup and configured within python

Local or managed server

Mayan EDMS should be deployed like any other Django project and preferably using virtualenv.

Install the correct utilities for use in Mayan:

  1. brew install tesseract
  2. brew install gpg
  3. brew install unpaper
  4. brew install ghostscript

To initialize a virtualenv to deploy the project do:

  1. cd /where-you-want-to-install-mayan
  2. virtualenv --no-site-packages mayan

Please note: On my installation the script files within the bin directory had a line in the beginning of the file to point to your version of python within the virtual environment. Because my installation went onto "Macintosh HD", there was a space in the script name and then the rest of the installation does not want to work. Change the first line of these scripts to point to your installation where the line does not include any spaces. "Don't remove the spaces, as this will resolve to an invalid path, replace the line with a path that contains no spaces (do a symbolic link if you have no other choice)". I also had to remove the '"' at the beginning and end of the line. The affected files are: easy_install, easy_install-2.7, pip, pip-2.7

Download and decompress the latest version of Mayan EDMS:

  1. cd mayan
  2. tar -xzvf mayan.tar.gz

Or clone the latest development version straight from github (default that I use):

  1. cd mayan
  2. git clone git://

To install the python dependencies easy_install can be used, however for easier retrieval a production dependencies file is included, to use it execute:

  1. cd mayan
  2. source ../bin/activate
  3. pip install -r requirements/production.txt

Create the database that will hold the data. Install any corresponding python database drivers. Update the file with you database settings.

If using the MySQL database manager, use the following commands:

  1. pip install MySQL-python

If using PostgresQL, enter the following:

  1. pip install psycopg2

Populate the database with the project’s schema doing:

NB!!! Update the file with your database, else the default sqllite database will be created.

  1. ./ syncdb --migrate

Collect the static files of the project into the static folder for serving via a webserver:

  1. ./ collectstatic

To test your installation, create a file called with the following content:

  1. DEBUG = True

Add the following to the file to point your mayan installation to the correct utilities installed above:

  1. CONVERTER_IM_CONVERT_PATH = "/usr/local/bin/convert" (ImageMagick Installed)
  2. CONVERTER_IM_IDENTIFY_PATH = "/usr/local/bin/identify" (ImageMagick Installed)
  3. OCR_TESSERACT_PATH = "/usr/local/bin/tesseract"
  4. OCR_UNPAPER_PATH = "/usr/local/bin/unpaper"

Add additional utility paths that you might need, such as ImageMagick, OpenOffice, LibreOffice, pdftotext, etc. This is only if you want to configure your environment for this.

Execute Django’s runserver command to launch a local instance of Mayan EDMS and point your browser to the URL: 127:0.0.1:8000, if everything was installed correctly you should see the login screen.

Your copy of Mayan is now ready for deployment. If you are going to run within a production environment, please follow the normal Django steps to deploy within a production environment.

gvandyk's picture
Solution Architect & MD of i-Kno