Paperless-ngx Setup with Docker Compose

Deploy Paperless-ngx, a digital document management system, using Docker Compose. This beginner-friendly guide includes detailed instructions on using the latest image and creating a superuser for access.

Paperless-ngx Setup with Docker Compose
Paperless logo

Transitioning to a paperless environment is straightforward with Paperless-ngx. In this guide, we'll deploy Paperless-ngx using Docker Compose. We'll then also cover creating a superuser account to access the deployed Paperless-ngx instance.

Why Paperless-ngx?

Paperless-ngx enables you to scan, organize, and access documents in a digital format, clearing out physical clutter. It's an open-source project that simplifies document management. Deploying with Docker offers easy setup and updates, providing an isolated environment for Paperless-ngx.


  • Docker and Docker Compose installed on your computer
  • Familiarity with basic Docker concepts
  • A server or personal computer to host Paperless-ngx

Setting Up Paperless-ngx:

  1. Prepare the Docker Compose File

In a new directory for your Paperless-ngx project, create a docker-compose.yml file. Use the following content, which specifies the image from

version: '3'
    container_name: paperless-ngx
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - "8000:8000"
    restart: unless-stopped


This setup ensures you're using the latest Paperless-ngx version, with volumes for persistent data and media storage, and exposes port 8000 for web interface access.

Start the Container

Open a terminal, navigate to your project's directory, and run:

docker-compose up -d

This command deploys Paperless-ngx in the background.

Creating a Superuser Account

After deployment, you need to create a superuser account to access the Paperless-ngx interface. Execute the following command to enter the running container:

docker-compose exec paperless-ngx manage createsuperuser

Follow the prompts to set a username, email, and password for your superuser account. This account allows you to log in to Paperless-ngx and manage your documents.

Accessing Paperless-ngx:

With the superuser created, access the Paperless-ngx web interface at http://localhost:8000. Log in with your superuser credentials to start uploading and managing your digital documents.

Configuring IMAP for Document Reception:

To enable Paperless-ngx to receive documents via an email account, add the necessary IMAP configuration to your docker-compose.yml file. This involves specifying environment variables that tell Paperless-ngx how to log into your email account and where to find new documents. Here’s an example of what these settings might look like for a generic email account:


Replace the host, port, user, and pass values with those of your email provider. The PAPERLESS_CONSUMPTION_MAIL_INBOX is typically set to INBOX, but you can specify a different folder if you prefer. Ensure SSL is enabled for a secure connection to your email server. After adding these configurations to your Docker Compose file and restarting your Paperless-ngx container, it will start checking the specified email for new documents to import automatically.

Remember, the exact settings will depend on your email provider, so you might need to consult their documentation for IMAP details. Adding this configuration turns Paperless-ngx into an even more powerful tool by streamlining the addition of new documents to your digital archive directly from your email.

Using Paperless-ngx streamlines document management, making it easier to transition to a digital environment.