If you follow this document and still have troubles, please open an issue on GitHub: so I can fill in the gaps.

This guide is split into two parts: short one and very detailed one. Short Version is meant for people who are confortable with development tools like Python, Django, pip, git or even gcc. In this case I will skip most of details as they will sound boring for such persons.

Detailed Version is for people who probably heard of Python - as programming language - but do not have any experience working with it. Any form of prior programming (in ruby, perl, java, C/C++) experience will help you to grasp the concepts quicker.

In both versions of this guide you need to know what is a command line terminal and how to work with it. In general Papermerge is a Linux/Unix based software. In this guide I will use Ubuntu 20.04 as example, but this instructions can be adopted easily for any Linux distribution.

Short Version

First download the sorce code. In this guide we clone latest stable version 1.5.5 into folder PapermergeDMS (located in home folder):

bash Clone repository
$ git clone --branch 1.5.5  PapermergeDMS
  1. Install required Ubuntu 20.04 LTS deb packages:

bash Install required dependencies
$ sudo apt install build-essential \
    python3-pip \
    python3-venv \
    git \
    imagemagick \
    poppler-utils \
    pdftk \
    tesseract-ocr \
    tesseract-ocr-eng \
    tesseract-ocr-deu \
    tesseract-ocr-fra \
  1. Create python virutal environment and activate it:

bash Create and activate python virtual environment
$ cd ~/PapermergeDMS
$ python3 -m venv .venv --system-site-packages
$ source .venv/bin/activate

Alternativelly you can create python virtual environment with command:

bash Create python virtual environment
$ virtualenv .venv -p python3.7

Advantage of last command is that you can specify exact python version. Papermerge requires python version >= 3.7

  1. Install necessary dependencies:

bash Install python dependencies, like Django for example
$ pip3 install -r requirements/base.txt
  1. Initialize SQLite database with:

bash Run migrations
$ ./ migrate
  1. Create a user for Papermerge instance:

bash Create superuser/administrative account for web user
$ ./ createsuperuser
  1. Start webserver with:

bash Run built-in web server
$ ./ runserver <IP>:<PORT>

If no specific IP or PORT is given, the default is also known as http://localhost:8000/.

7. In a separate window, change to the project’s root directory again, but this time, you should start the worker script with:

bash Run papermerge worker instance
$ ./ worker

Detailed Version

Step 1 - Python and Friends

Papermerge is written in Python. First thing you need to make sure python interpreter is installed. Ubuntu 20.04 comes with python interpreter already installed. However, the command to invoke python interpreter is python3:

bash Check python version
$ python3 --version
Python 3.8.2


Python community now transitions from python2 (which is not maintained anymore) to python3. This is why in many Linux distributions you can access python interpreter either with python command or with python3 command.


Make sure your python is at least version 3.7

A close python’s friend is pip command. pip is python’s package manager. Similar as with python interpreter story - there might be either pip or pip3 - latter is specifically for python version 3. We will use pip3:

bash Install pip3
$ sudo apt install python3-pip

Make sure it was installed:

bash Make sure pip3 is avilable
$ pip3 --version
pip 20.0.2 from /usr/lib/python3/dist-packages/pip (python 3.8)

Another package which you need to install is python3-venv. This one will be used in Step 2 we’ll learn and setup python virtual environment:

bash Install python’s virtual environment
$ sudo apt install python3-venv

Although Papermerge is written in python, it uses some special python modules which are compiled from C sources and used in binary form. This means that you need gcc compiler installed as well.

In Ubuntu 20.04, gcc is available via built-essential package:

bash Install ubuntu build-essential package
sudo apt install build-essential

Double check that gcc was installed:

bash Double check that gcc was installed
$ gcc --version
gcc (Ubuntu 9.3.0-10ubuntu2) 9.3.0
Copyright (C) 2019 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO

Ok, great! We have to install one more utility - git. Strictly speaking, you don’t need git, because you can download the tarball and unzip (or untar or extract) sources. But let’s stick with git:

bash Install git
$ sudo apt install git

Double check that git was installed:

bash Double check that git was installed
$ git --version
git version 2.25.1

And now clone the latest stable version of Papermerge directly from GitHub repository:

bash Clone latest stable release
$ git clone --branch v1.5.5  PapermergeDMS


As of writing this - latest stable version of Papermerge is 1.5.5, thus the argument --branch with respective version. Also, notice that repository was cloned inside folder named PapermergeDMS, you can choose whatever title for that folder suites you.

From now on, I will refer to PapermergeDMS folder as project root or top level folder of the project

Step 2 - Python Virtual Environment

Change directory to project’s root (folder where you cloned/extracted sources):

bash Change to project’s directory
$ cd PapermergeDMS

Our goal in this step is to install python dependencies - like Django for example. Most important dependencies - without which project won’t start - are listed in requirements/base.txt (relative to project’s root).

The command to do that is as simple as pip install -r requirements/base.txt - but please don’t rush to type it yet. We need to clarify the concept of python virtual environment first.

If you simply type pip insall -r requirements/base.txt - it will install packages system-wide. A better approach is to install dependencies per project. So, the place designated for python packages specific for this project is called a virtual environment. Let’s create a python virtual environment and name it .venv:

bash Create python virtual environment
$ python3 -m venv .venv --system-site-packages


For virtual environment you can choose whatever name you want. For example you can choose to name your virtual environment py37, in that case command will be python3 -m venv py37. However, I chose .venv because in Unix/Linux dotted folders have special meaning - they are hidden so to speak.


--system-site-packages is necessary, it will install a package called wheel. Without wheel package, pip install later will issue warning.

Alternatively you can create python virtual environment with following command:

bash Another way to create python virtual environment
$ virtualenv .venv -p python3.7

Advantage of last command is that it specifies exact python version.


Papermerge requires python version >= 3.7

Next we need to activate virtual environment:

bash Activate python virtual envitonment
$ source .venv/bin/activate

Terminal’s prompt (bash - in Ubuntu) will change to indicate that python virtual environment is active.



Python virtual environment is just a directory where python packages will be installed. Activating python environment is basically changing your current PATH variable - this is exactly what source .venv/bin/activate command does. If you will run echo $PATH you will notice that PapermergeDMS/.venv/bin is first in path, this means that python interpreter first of all will look up for its dependencies there.

And now, with python virtual environment active, let’s install Papermerge dependencies:

bash Install python dependencies
$ source .venv/bin/activate # a reminder to run this first
$ pip3 install -r requirements/base.txt

At this point, all python packages were installed inside directory .venv/lib/python3.8/site-packages and that directory is first one in your path.

Step 3 - Manage Command

Papermerge is based on Django Web Framework. Django provides a script which is used to run all project related commands. script is located in project’s root directory.

First let’s run migrations:

bash Run migrations
$ ./ migrate


At this point you will see warnings about missing binary dependencies. We deal with them little bit later when we will discuss ./ check command.

run migrations - in django’s jargon means that you prepare the database. By default Papermerge (as any Django based project) uses sqlite database - which is stored in a single file. ./ migrate command will create that file (it is called db.sqlite3 and is in project’s root directory) and create database schema for the project.

We are not ready yet, but at this point, you can built-in web server and access login screen:

bash Run builtin web server
$ ./ runserver

runserver command will start web server on port 8000. You can access login screen via any web browser by pointing it to http://localhost:8000/


But as I mentioned, we are not ready yet. First of all, when you run ./ runserver command you probably noticed couple of warnings. To see if all binary dependencies were installed run following command:

$ ./ check

On freshly installed Ubuntu 20.04 LTS you will see following warnings:

bash Possible warning messages
System check identified some issues:

?: Papermerge can't find convert. Without it, image resizing is not possible.
        HINT: Either it's not in your PATH or it's not installed.
?: Papermerge can't find identify. Without it, it is not possible to count pages in TIFF.
        HINT: Either it's not in your PATH or it's not installed.
?: Papermerge can't find tesseract. Without it, OCR of the documents is impossible.
        HINT: Either it's not in your PATH or it's not installed.
?: file was found. Following locations attempted /etc/,
        HINT: Create one of those files or point PAPERMERGE_CONFIG environment name to it.

System check identified 5 issues (0 silenced).

This means that you need to install all above dependencies. Let’s install all of them in one shot:

bash Install tesseract, imagemagick and poppler-utils
sudo apt install imagemagick \
    poppler-utils \
    tesseract-ocr \
    tesseract-ocr-eng \
    tesseract-ocr-deu \
    tesseract-ocr-fra \

When installation is complete, run check again:

bash Check again for warnings
$ ./ check

System check identified some issues:

?: file was found. Following locations attempted /etc/,
        HINT: Create one of those files or point PAPERMERGE_CONFIG environment name to it.

System check identified 1 issue (0 silenced).

To silence last warning, just create an empty file in project’s root, we will turn our attention to that file little bit later:

bash Create an empty file
$ touch

Step 4 - Superuser

It’s time to create administrative (superuser) user for your Papermerge instance:

bash Create web administrative user
$ ./ createsuperuser

The username and password you will type above you will use as login credentials. So, start server again (in case it is not running):

bash Run built-in web server
$ ./ runserver

Point your web browser to http://localhost:8000 and use superuser’s username/password to login.

Step 5 - Worker

In a separate window, change to the project’s root directory again, but this time, you should start the worker with ./ worker. Remember to activate python virtual environment first:

bash Start papermerge worker instance
$ cd ~/PapermergeDMS
$ source .venv/bin/activate
$ ./manage worker

Worker is the part which performs OCR process. For correct function of Papermerge you must have both parts running:

  • main app - the one which you start with ./ runserver

  • worker - the one which you start with ./ worker

Now, you can start uploading documents. Remember that only PDF, TIFF, jpeg and png file_formats are supported.


Step 6 - Configurations

By default, you don’t need configuration file. However, if there is no configuration file - Papermerge will issue a warning. In one of previous steps we created an empty configuration file:

bash Create empty configuration file
$ cd ~/PapermergeDMS
$ touch # it is empty now


What is the purpose of empty configuration file? It has one - it raises awareness of administrator that such file exists. The logic is following - if administrator created => Papermerge application immediately concludes admin is aware of such file and silence the warning message. Again - it is absolutely OK to leave file empty.

By default, in language dropdown menu, two languages will be displayed German and English. You can change that with following configuration:

Python Content of
    'eng': 'English',
    'deu': 'Deutsch',
    'spa': 'Español',
    'fra': 'Français'

Now four languages will be displayed in language dropdown.


In previous steps we installed english, spanish, french and german tesseract language packs (packages named tesseract-ocr-eng, tesseract-ocr-deu, tesseract-ocr-fra, tesseract-ocr-spa). For each language you want to OCR you need to have tesseract language pack installed.

Learn more Papermerge configurations in settings

What’s Next?

Once you’ve tested things and are happy with the work flow, you should secure the installation and automate the process of starting the webserver and worker. Server Configurations explains different configuration scenarios of how you can make your bare metal setup - more stable.