Paperless-ngx Setup Guide: Docker Compose, From Scanner to Searchable Archive

Guide · Start

Affiliate links. Disclosure

Date / checked: 2026-10-25. Paperless-ngx version: v3.3.4 (GitHub release, published 2026-10-23 07:26 JST). The image tag ghcr.io/paperless-ngx/paperless-ngx:3.3.4 exists on GHCR (checked 2026-10-25).

Paperless-ngx turns scanned paper into a searchable archive. Its docs recommend the official install script for most users, with Docker Compose templates if you want manual control. Bare metal runs on Linux only. After setup, point your scanner at the consume folder and Paperless OCRs, tags and files each document.

Choose an install route (official)

The docs list three routes: the installation script ("recommended for most users"), Docker Compose templates (manual control) and bare metal (advanced). "For most users, Docker is the best option." Paperless bare metal "runs on Linux only, Windows is not supported."

Prerequisite for both Docker routes: Docker and Docker Compose installed.

Option A: the official install script

bash
bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

The docs say: "If piping into a shell directly from the internet makes you nervous, inspect the script first!" The script asks configuration questions, creates the files, pulls the image, starts the containers and creates your superuser.

Option B: Docker Compose (manual)

  1. From the project's [docker/compose](https://github.com/paperless-ngx/paperless-ngx/tree/v3.3.4/docker/compose) directory, download one docker-compose.*.yml for your database and save it as docker-compose.yml. Also download docker-compose.env and .env. The docs recommend PostgreSQL for new installs; pick a -tika file if you want Office document support.
  2. Pin the version. The official PostgreSQL template (at tag v3.3.4) uses image: ghcr.io/paperless-ngx/paperless-ngx:latest; we suggest changing that line to:
yaml
    image: ghcr.io/paperless-ngx/paperless-ngx:3.3.4
  1. Change the consume/media paths if you want bind mounts, e.g. - <CONSUME_DIR>:/usr/src/paperless/consume. To change the port: ports: - 8010:8000.
  2. In docker-compose.env, set USERMAP_UID and USERMAP_GID to your host user's values (id -u, id -g) so the scanner/host can write to the consume folder.
  3. Start:
bash
docker compose pull
docker compose up -d
  1. Open http://127.0.0.1:8000 (or your host and port). On first access you're prompted to create a superuser.

The official PostgreSQL template sets POSTGRES_PASSWORD: paperless. Change it (and the matching Paperless DB password) before you put real documents in. The docs also suggest a separate non-superuser account for daily use, because "superuser accounts have full access to all objects and documents". Don't expose port 8000 to the internet without a reverse proxy and HTTPS (see the docs' wiki link on reverse proxies).

Scanner to archive

Paperless watches the consume directory: point your scanner's "scan to folder"/SMB target at the host folder you mapped to /usr/src/paperless/consume. If that folder is on NFS or another filesystem without inotify, set PAPERLESS_CONSUMER_POLLING_INTERVAL to a positive number (per the docs).

Low-power hardware tips (from the docs)

For Raspberry Pi-class devices the docs suggest: SQLite, PAPERLESS_OCR_PAGES=1, fewer PAPERLESS_TASK_WORKERS/PAPERLESS_THREADS_PER_WORKER, PAPERLESS_OCR_CLEAN=none, and PAPERLESS_WEBSERVER_WORKERS=1 on Docker.

Backup and restore with the document exporter (official)

Source: Paperless-ngx docs/administration.md at v3.3.4 (read from the raw file on GitHub, checked 2026-10-25).

The docs say the document exporter "exports all your documents, thumbnails, metadata, and database contents to a specific folder." Before a backup, make sure Paperless "is not actively consuming documents." The export does not include API tokens, so you'll need to generate them again after an import.

Export (Docker Compose, while Paperless is running). With the official compose files, ../export inside the container maps to the export folder on your host:

bash
cd /path/to/paperless
docker compose exec -T webserver document_exporter ../export

The docs suggest -T for cron jobs, because it suppresses "The input device is not a TTY" errors. Useful documented options:

Restore into a completely empty Paperless-ngx install (empty database and directories). Put the export inside the export folder, then run:

bash
docker compose exec webserver document_importer ../export

Add --passphrase if the export was encrypted.

"You cannot import the export generated with one version of paperless in a different version of paperless." Restore into the same version, 3.3.4, then upgrade.

Alternative for Docker: back up the Docker volumes (usually under /var/lib/docker/volumes, root access needed): paperless_media (documents), paperless_data (auxiliary data, plus the SQLite DB if you use SQLite) and paperless_pgdata (PostgreSQL) or paperless_dbdata (MariaDB).

Upgrading from v2

The docs say upgrading an existing install "from v2 to v3 has its own breaking changes and required steps" — read the v3 migration guide linked from the setup page first, and take a backup.

Related: back up with restic · starter stack

Sources

Related guides