You need a Linux machine or Unix-like setup (theoretically an Apple machine should work) that has the following software installed:

Notably, you should confirm how you access your Python3 installation. Many Linux distributions will install Python3 in parallel to Python2, using the names python3 and python respectively. The same goes for pip3 and pip. Running Paperless with Python2 will likely break things, so make sure that you’re using the right version.

For the purposes of simplicity, python and pip is used everywhere to refer to their Python3 versions.

In addition to the above, there are a number of Python requirements, all of which are listed in a file called requirements.txt in the project root directory.

If you’re not working on a virtual environment (like Docker), you should probably be using a virtualenv, but that’s your call. The reasons why you might choose a virtualenv or not aren’t really within the scope of this document. Needless to say if you don’t know what a virtualenv is, you should probably figure that out before continuing.

Problems with Imagemagick & PDFs

Some users have run into problems with getting ImageMagick to do its thing with PDFs. Often this is the case with Apple systems using HomeBrew, but other Linuxes have been a problem as well. The solution appears to be to install ghostscript as well as ImageMagick:

$ brew install ghostscript
$ brew install imagemagick
$ brew install libmagic

Python-specific Requirements: No Virtualenv

If you don’t care to use a virtual env, then installation of the Python dependencies is easy:

$ pip install --user --requirement /path/to/paperless/requirements.txt

This will download and install all of the requirements into ${HOME}/.local. Remember that your distribution may be using pip3 as mentioned above.

Python-specific Requirements: Virtualenv

Using a virtualenv for this is pretty straightforward: create a virtualenv, enter it, and install the requirements using the requirements.txt file:

$ virtualenv --python=/path/to/python3 /path/to/arbitrary/directory
$ . /path/to/arbitrary/directory/bin/activate
$ pip install  --requirement /path/to/paperless/requirements.txt

Now you’re ready to go. Just remember to enter (activate) your virtualenv whenever you want to use Paperless.


As generation of the documentation is not required for the use of Paperless, dependencies for this process are not included in requirements.txt. If you’d like to generate your own docs locally, you’ll need to:

$ pip install sphinx

and then cd into the docs directory and type make html.

If you are using Docker, you can use the following commands to build the documentation and run a webserver serving it on port 8001:

$ pwd

$ docker build -t paperless:docs -f docs/Dockerfile .
$ docker run --rm -it -p "8001:8000" paperless:docs