Paperless-ngx

Document management system that scans, indexes and archives paper documents.

Replaces

Paid document management services, such as Evernote and Docparser.

All open-source alternatives to Docparser, Evernote

Difficulty

Difficulty: Hard

3 services (2 database or broker: valkey, postgres), 6 volume mounts, 1 env value to set, no elevated host access. Heuristic score 6 of 11: hard.

Stack

Python (language), Valkey (database), PostgreSQL (database)

Deployment

docker_compose

Requirements

Not stated.

License

GPL-3.0 (OSI-approved open source)

Read from github.com/paperless-ngx/paperless-ngx/blob/232f9c8/LICENSE

Business model

Unknown

The README at the pinned commit does not state a business model, so it stays unknown.

Source: github.com/paperless-ngx/paperless-ngx/blob/232f9c8/README.md, read on 2026-10-22.

Repository

paperless-ngx/paperless-ngx

GitHub stats

Stars: 46,986
Forks: 3,263
Open issues and pull requests: 11
Last push: 2026-10-22
Latest release: v3.3.3
Released: 2026-10-19

From the GitHub API on 2026-10-22. These numbers are a snapshot, not live. GitHub detected the license as GPL-3.0.

Compose file

Config check passed docker compose config exited 0 on this exact file on 2026-10-22.

docker-compose.postgres.yml Version 1

# Docker Compose file for running paperless from the Docker Hub.
# This file contains everything paperless needs to run.
# Paperless supports amd64, arm and arm64 hardware.
#
# All compose files of paperless configure paperless in the following way:
#
# - Paperless is (re)started on system boot, if it was running before shutdown.
# - Docker volumes for storing data are managed by Docker.
# - Folders for importing and exporting files are created in the same directory
#   as this file and mounted to the correct folders inside the container.
# - Paperless listens on port 8000.
#
# In addition to that, this Docker Compose file adds the following optional
# configurations:
#
# - Instead of SQLite (default), PostgreSQL is used as the database server.
#
# To install and update paperless with this file, do the following:
#
# - Copy this file as 'docker-compose.yml' and the files 'docker-compose.env'
#   and '.env' into a folder.
# - Run 'docker compose pull'.
# - Run 'docker compose up -d'.
#
# For more extensive installation and update instructions, refer to the
# documentation.
services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data
  db:
    image: docker.io/library/postgres:18
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql
volumes:
  data:
  media:
  pgdata:
  redisdata:

From the app's own repository: github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docker/compose/docker-compose.postgres.yml.

Compose file from the app repository.

Install

Docker with the Compose plugin (github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docs/setup.md)
A host with Docker and the Docker Compose plugin. This entry runs from a compose file.
Save the compose file as docker-compose.yml (github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docker/compose/docker-compose.postgres.yml)
Use the compose file shown above.

Save as docker-compose.env next to the compose file (github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docker/compose/docker-compose.env)

###############################################################################
# Paperless-ngx settings                                                      #
###############################################################################

# See http://docs.paperless-ngx.com/configuration/ for all available options.

# The UID and GID of the user used to run paperless in the container. Set this
# to your UID and GID on the host so that you have write access to the
# consumption directory.
#USERMAP_UID=1000
#USERMAP_GID=1000

# See the documentation linked above for all options. A few commonly adjusted settings
# are provided below.

# This is required if you will be exposing Paperless-ngx on a public domain
# (if doing so please consider security measures such as reverse proxy)
#PAPERLESS_URL=https://paperless.example.com

# Required. A unique secret key for session tokens and signing.
# Generate with: python3 -c "import secrets; print(secrets.token_urlsafe(64))"
PAPERLESS_SECRET_KEY=change-me

# Use this variable to set a timezone for the Paperless Docker containers. Defaults to UTC.
#PAPERLESS_TIME_ZONE=America/Los_Angeles

# The default language to use for OCR. Set this to the language most of your
# documents are written in.
#PAPERLESS_OCR_LANGUAGE=eng

# Additional languages to install for text recognition, separated by a whitespace.
# Note that this is different from PAPERLESS_OCR_LANGUAGE (default=eng), which defines
# the language used for OCR.
# The container installs English, German, Italian, Spanish and French by default.
# See https://packages.debian.org/search?keywords=tesseract-ocr-&searchon=names
# for available languages.
#PAPERLESS_OCR_LANGUAGES=tur ces

Save as .env next to the compose file (github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docker/compose/.env)
```
COMPOSE_PROJECT_NAME=paperless
```
What the compose file check ran with (github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docs/setup.md)
The compose file check ran together with docker-compose.env (saved as docker-compose.env) and .env (saved as .env) from the same commit. The folder held only these files. The setup guide tells the reader to download one docker-compose file for the chosen database, save it as docker-compose.yml, download docker-compose.env and .env into the same folder and run docker compose up -d.
Start it (github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docs/setup.md)
```
docker compose up -d
```
Open the app (github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docker/compose/docker-compose.postgres.yml)
Open http://localhost:8000. The compose file publishes host port 8000 for the webserver service. The docs say Paperless-ngx should be available at http://127.0.0.1:8000.

Compose file check: config_ok on 2026-10-22.

Gotchas and maintenance

Gotchas

Some images use the latest tag or no tag. Images without a pinned version: webserver: ghcr.io/paperless-ngx/paperless-ngx:latest. A later pull can get a different version. (github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docker/compose/docker-compose.postgres.yml, checked 2026-10-22)
The compose file publishes host ports. Host ports: 8000 (webserver). A port without a host address listens on all host network interfaces. (github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docker/compose/docker-compose.postgres.yml, checked 2026-10-22)
The compose file mounts host folders. Host paths mounted into containers: ./export at /usr/src/paperless/export (webserver), ./consume at /usr/src/paperless/consume (webserver). (github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docker/compose/docker-compose.postgres.yml, checked 2026-10-22)
The example env file docker-compose.env has placeholder values. The example env file sets placeholder text for: PAPERLESS_SECRET_KEY. Replace them before you rely on the install. (github.com/paperless-ngx/paperless-ngx/blob/232f9c8/docker/compose/docker-compose.env, checked 2026-10-22)

Signals

Open issues and pull requests: 11
Last push: 2026-10-22 (0 days before this page was built)
Latest release: v3.3.3 on 2026-10-19 (3 days before this page was built)