Paperless-ngx backup and restore: what to keep

Choose a backup route

Paperless documents an exporter that includes documents, thumbnails, metadata, and database contents. Docker installations can instead back up persistent storage and the database consistently. Which route fits depends on how the instance is deployed. Copying only PDFs preserves readable files but not the complete application state.

Record the environment

Write down the Paperless version, database type, persistent volume locations, and relevant configuration. Keep a protected copy of deployment files and the secrets needed to restore. A backup folder without instructions can be difficult to use after the person who configured the server leaves. Store the recovery instructions separately from a machine that might fail.

Create an export

For a Compose deployment whose service is named webserver, the documented invocation has the following shape. Confirm the container’s export path is mapped to persistent host storage. Pause incoming document consumption while producing a consistent backup.

docker compose exec -T webserver document_exporter ../export

Check --help for the version you run. Do not add deletion or overwrite options from an unrelated example.

Restore the matching version first

Use an isolated instance and follow the importer instructions for the same Paperless version as the export. The project warns that database changes can make cross-version imports incompatible. Its documentation also notes that API tokens are not included in exporter backups and need regeneration. Plan any software upgrade after confirming the restore.

Check what a colleague would need

Compare document counts, open original and archived files, search for a known phrase, and inspect a few tags and permissions. Keep a dated result with the backup. Then ask another authorized person to find the instructions and identify the newest verified copy. A successful backup command is only the beginning of the recovery test.