How to back up and restore Paperless-ngx

What Paperless-ngx stores

Paperless-ngx is an open-source (GPL-3.0) document manager that runs OCR on your scans and keeps them searchable. This guide assumes the official v3.2.1 Docker Compose files in /opt/paperless. Their .env sets COMPOSE_PROJECT_NAME=paperless, which prefixes the volume names:

docker volume ls --filter name=paperless_

PAPERLESS_SECRET_KEY signs sessions and tokens; a restore under a different value logs everyone out but loses nothing. If you set PAPERLESS_EMPTY_TRASH_DIR, back that folder up too.

Exporter or volumes?

Paperless-ngx's docs describe both. This guide uses the portable one, the exporter, as the main backup:

Run the document exporter

The official compose files mount the export folder beside them at /usr/src/paperless/export, and commands run from /usr/src/paperless/src, so the target is ../export. From /opt/paperless:

docker compose exec -T webserver document_exporter ../export --delete --no-progress-bar

• -T stops docker compose exec from allocating a terminal; without it, cron runs fail with The input device is not a TTY.
• The first run copies everything. Later runs copy only files whose modification time or size changed, and rewrite manifest.json and metadata.json. -c (--compare-checksums) compares checksums instead, more slowly.
• --delete removes files that no longer belong to the export, such as deleted documents. Use it only on a folder that holds nothing else.
• --no-progress-bar keeps the cron log readable.
• The exporter holds Paperless's media lock while it runs, so a document being consumed waits instead of landing half in the export.

Other flags worth knowing:

• -p (--use-folder-prefix) sorts files into originals, archive and thumbnails folders instead of one flat folder.
• -f (--use-filename-format) names files with your PAPERLESS_FILENAME_FORMAT instead of [date created] [correspondent] [title].
• -na and -nt skip archive files and thumbnails; after an import they are missing until document_archiver and document_thumbnails recreate them.
• -z (--zip) writes one zip named after today's date, such as export-2026-10-04.zip; -zn sets another name. It can't be combined with -c or -cj, and together with --delete it removes everything else in the folder, older zips included.
• --passphrase encrypts the mail account passwords and OAuth tokens in the export, otherwise plain text (No passphrase was given, sensitive fields will be in plaintext). It leaves documents unencrypted, and an export made with it can't be imported without it.
• --data-only exports the database without files, for database upgrades.

API tokens are never exported.

Schedule it

The export folder mirrors the current state; it is not a history. Run it nightly and let a backup tool keep dated versions elsewhere:

15 2 * * * root cd /opt/paperless && docker compose exec -T webserver document_exporter ../export --delete --no-progress-bar >> /var/log/paperless-export.log 2>&1

Time one run by hand and schedule the off-site copy after it. Check free space first: the export repeats what the media volume holds.

du -sh "$(docker volume inspect --format '{{ .Mountpoint }}' paperless_media)"

To keep dated copies on the server instead, export zips and prune them. Each zip is a full copy, written as export-<date>.zip.tmp and renamed when finished:

15 2 * * * root cd /opt/paperless && docker compose exec -T webserver document_exporter ../export --zip --no-progress-bar >> /var/log/paperless-export.log 2>&1
45 4 * * * root find /opt/paperless/export -name 'export-*.zip' -mtime +7 -delete

Or back up the volumes and the database

Dump the database first and copy the media second, so the worst case is a few files the database doesn't know (reported as orphaned), not rows pointing at missing files. With PostgreSQL (the db service):

install -d -m 700 /var/backups/paperless

docker compose exec -T db pg_dump -U paperless -d paperless | gzip > /var/backups/paperless/paperless-db-$(date +%F).sql.gz

With SQLite, the database is db.sqlite3 in paperless_data, and Paperless-ngx 3 opens it in WAL mode, so recent changes may still sit in db.sqlite3-wal. Copy it with SQLite's backup command from the host (apt install sqlite3), not cp:

sqlite3 "$(docker volume inspect --format '{{ .Mountpoint }}' paperless_data)/db.sqlite3" ".timeout 10000" ".backup '/var/backups/paperless/db.sqlite3'"

Then archive paperless_media as in Docker volume backups. MariaDB is in Backing up a database in Docker Compose; SQLite backups explains .backup. Restore onto the same version or newer, then run the sanity checker below.

Encrypt the off-site copy

Paperless-ngx stores documents as plain files, often tax returns, contracts and medical letters, and the export adds readable names, user accounts and, without --passphrase, mailbox passwords. Encrypt before anything leaves the server:

• restic encrypts everything in its repository with AES-256 and only uploads what changed, which suits an export folder that changes a little each night.
• Or pack the folder with tar and encrypt it with gpg, as Encrypting backups shows, then copy the file with rclone.

Restore with the document importer

The importer needs an empty Paperless-ngx of the version that made the export. metadata.json in the export records it; for a zip, read it with unzip -p export-2026-10-04.zip metadata.json:

grep version /opt/paperless/export/metadata.json

1. On the new server, put docker-compose.yml, docker-compose.env and .env from your backup in /opt/paperless, and change the webserver's image: from latest to that version, such as ghcr.io/paperless-ngx/paperless-ngx:3.2.1.
2. Put the export into /opt/paperless/export: the folder's contents, or the zip.
3. Leave PAPERLESS_ADMIN_USER unset and don't create an account in the browser. The importer expects no users and no documents.
4. Start the stack with docker compose up -d and wait for the web page to load.

docker compose exec -T webserver document_importer ../export

For a zip, name the file: ../export/export-2026-10-04.zip; it is unpacked inside the container first, so leave room. The importer checks every file in the manifest, loads the database, copies the files and rebuilds the search index. Add --passphrase if the export has one, then log in with your old account and create new API tokens.

Upgrades, versions and switching databases

• Upgrades don't need the exporter: stop the stack, back up, docker compose pull, docker compose up; the new image migrates the database as it starts. Read the release notes first.
• An import needs matching versions. The docs warn that an export can't be imported into a different version, because it is an exact image of the database and migrations change its layout. The importer only warns about a mismatch and carries on, so pin the image tag on the new server, import, then upgrade.
• Switching database engines is what the exporter is for. Paperless-ngx's docs up to 2.20 called an export followed by an import into a clean installation the best way to migrate between database types: export from SQLite, start an empty install of the same version with PAPERLESS_DBENGINE=postgresql, import.
• A new PostgreSQL or MariaDB major version: follow the database's own upgrade docs, or export and import with --data-only into a newly created database, without changing any paths. See PostgreSQL major upgrades.

Test a restore

Import the off-site copy, not the live export folder, into a private second instance. A throwaway server is simplest; on the same server, use a separate folder and project name, with room for another copy of every document:

mkdir -p /opt/paperless-restore-test/export

cp /opt/paperless/docker-compose.yml /opt/paperless/docker-compose.env /opt/paperless/.env /opt/paperless-restore-test/

Edit the copies before you run anything:

• .env: COMPOSE_PROJECT_NAME=paperless-restore-test, so the copy gets its own containers and volumes.
• docker-compose.yml: pin the image to the export's version, and change the port to "127.0.0.1:8001:8000" so only the server can reach it.
• docker-compose.env: add PAPERLESS_URL=http://localhost:8001, PAPERLESS_EMAIL_TASK_CRON=disable and PAPERLESS_WORKFLOW_SCHEDULED_TASK_CRON=disable. The last two stop the copy from fetching your real mailboxes, and applying your mail rules to them, and from running scheduled workflows.

Put the restored export into /opt/paperless-restore-test/export, then, in that folder, start the copy, import and check:

docker compose up -d

docker compose exec -T webserver document_importer ../export

docker compose exec -T webserver document_sanity_checker

The sanity checker compares every original and archive file's checksum with the database and reports missing or unreadable files. Then log in through an SSH tunnel at http://localhost:8001, compare the document count with the live instance and open a few old ones:

ssh -N -L 8001:127.0.0.1:8001 root@<server-ip>

Remove the copy afterwards. down -v deletes the containers and volumes of this project only, which is why the project name matters:

docker compose down -v

rm -rf /opt/paperless-restore-test

Time the import; that is most of your recovery time. Testing restores turns this into a routine.

Common errors

Frequently asked questions

Where does Paperless-ngx store my documents?

In the media volume, under documents/originals, with archived PDF/A copies in documents/archive and thumbnails in documents/thumbnails. The database and search index are in the data volume, or in PostgreSQL or MariaDB if you use one.

Is document_exporter a full backup?

Nearly: it exports every document file and the whole database, including users, mail accounts and settings. API tokens are left out, and the export only imports into an empty install of the same version.

Can I import a Paperless-ngx export into a newer version?

The docs say to match versions. Install the version recorded in the export's metadata.json, import, then upgrade normally.

Do I need to back up the search index?

No. The Docker image checks the index at every start and rebuilds it when needed, and document_index reindex rebuilds it by hand.

How do I move Paperless-ngx from SQLite to PostgreSQL?

Export with document_exporter, start an empty install of the same version with PAPERLESS_DBENGINE=postgresql, and import with document_importer.