Paperless-ngx Backup & Restore: The Right Strategy
Create a secure, incremental Paperless-ngx backup with Docker and restore your documents in an emergency. Includes instructions for PostgreSQL and MariaDB, step by step.

Contents
Paperless-ngx 3.4.2PostgreSQL 18MariaDB 11.8Docker 29.9Ubuntu 24.04A Document Management System (DMS) like Paperless-ngx is the heart of the paperless office. But what happens if the server fails, an update goes wrong, or the database becomes corrupt? Without a proper backup, not only are your settings lost, but in the worst-case scenario, your important documents are gone too.
I show you a backup strategy that secures both the database and the files, saves space and runs on its own. It works with PostgreSQL and with MariaDB. I tested it with Paperless-ngx 3.4.2 on a fresh Ubuntu 24.04 server, once with PostgreSQL 18 and once with MariaDB 11.
Why simply copying folders isn’t enough
Many users simply copy the entire Docker folder. This might work, but it carries risks:
- Database Consistency: If you copy the database files while the container is running, the backup may be corrupt and unusable.
- Internal Links: Paperless links documents in the database with files in the file system. If these are not backed up synchronously, problems will arise.
The cleanest solution is a combination of an SQL dump of the database and the built-in Document Exporter of Paperless.
The Strategy
We want to achieve the following:
- Create a clean dump of the database.
- Bring the documents into a processable format with the Paperless Exporter (this also writes metadata into
jsonfiles). - Back up this data incrementally to save space (we don’t want to copy 10 GB every day if only two PDFs changed).
- Delete old backups automatically (retention policy).
The export also contains the database content (tags, correspondents, users, settings) in the file manifest.json. For the restore, you normally only need the export. The SQL dump is only an additional safety net.
Preparation
At the top of the article, you can enter your values: paths, service names and database access. They then appear in the commands.
In the compose.yaml, every entry directly under services: has a service name, for example db and webserver. Docker Compose derives container names from them when it starts, unless you set container_name yourself. The script uses docker compose exec, and this command always wants the service name (webserver, db).
Create a file on your server, e.g., backup-paperless.sh.
nano {{paperless_dir}}/backup-paperless.shPaste the following content:
#!/bin/bash
set -e
set -o pipefail
# --- CONFIGURATION ---
# Path where the backups should be stored
BACKUP_BASE_DIR="{{backup_dir}}"
# Your Paperless directory (where compose.yaml is located)
PAPERLESS_DIR="{{paperless_dir}}"
# Name of the symlink for the latest backup
LATEST_LINK="${BACKUP_BASE_DIR}/latest"
# Names of the SERVICES from compose.yaml (not the container names!)
# These are the entries directly under "services:".
DB_SERVICE="{{db_service}}"
WEBSERVER_SERVICE="{{webserver_service}}"
# Database credentials (from your compose.yaml)
DB_USER="{{db_user}}"
DB_NAME="{{db_name}}"
# How many days should backups be kept?
RETENTION_DAYS=30
DOCKER_COMPOSE_CMD="/usr/bin/docker compose"
echo "========================================================"
echo "Starting Paperless backup: $(date)"
echo "========================================================"
# All Compose commands run in the Paperless directory
cd "${PAPERLESS_DIR}"
# 1. Create new backup directory
DATE_STAMP=$(date +"%Y-%m-%d_%H-%M-%S")
BACKUP_DIR="${BACKUP_BASE_DIR}/${DATE_STAMP}"
mkdir -p "${BACKUP_DIR}"
# On an error, remove the incomplete backup again
trap 'rm -rf "${BACKUP_DIR}"' ERR
echo "[+] Creating backup directory: ${BACKUP_DIR}"
# 2. Back up the database (PostgreSQL)
echo "[+] Creating PostgreSQL dump..."
${DOCKER_COMPOSE_CMD} exec -T "${DB_SERVICE}" pg_dump -U "${DB_USER}" -d "${DB_NAME}" > "${BACKUP_DIR}/paperless-db.sql"
# Check if the dump is empty
if [ ! -s "${BACKUP_DIR}/paperless-db.sql" ]; then
echo "ERROR: Database dump is empty!"
exit 1
fi
echo " -> Database dump successful."
# 3. Export Paperless documents
echo "[+] Starting document_exporter..."
${DOCKER_COMPOSE_CMD} exec -T "${WEBSERVER_SERVICE}" document_exporter ../export --delete --no-progress-bar
echo " -> Document exporter executed successfully."
# 4. Back up documents incrementally with rsync and hard links
echo "[+] Synchronizing documents..."
if [ -d "${LATEST_LINK}" ]; then
LINK_DEST_OPTION="--link-dest=${LATEST_LINK}/documents"
echo " -> Previous backup found. Using hard links."
else
LINK_DEST_OPTION=""
echo " -> No previous backup found. Creating full copy."
fi
# Assumption: ./export is mounted in PAPERLESS_DIR
rsync -a --delete ${LINK_DEST_OPTION} "${PAPERLESS_DIR}/export/" "${BACKUP_DIR}/documents/"
echo " -> Documents synchronized."
# 5. Update 'latest' symlink
echo "[+] Updating 'latest' link."
ln -snf "${BACKUP_DIR}" "${LATEST_LINK}"
# 6. Delete old backups
echo "[+] Deleting backups older than ${RETENTION_DAYS} days..."
find "${BACKUP_BASE_DIR}" -maxdepth 1 -type d -not -name "latest" -not -path "${BACKUP_BASE_DIR}" -mtime +${RETENTION_DAYS} -exec rm -rf {} \;
echo " -> Cleanup complete."
echo "========================================================"
echo "Paperless backup completed successfully!"
echo "========================================================"- If a step fails,
trapremoves the half-finished backup directory. Otherwise, the next run would take an incomplete backup as the basis for the hard links. --deleteremoves files of documents you deleted in Paperless from the export folder.--no-progress-barkeeps the log clean.- The last
findline excludes the backup folder itself.
Make the script executable
For the script to run, we need to give it the appropriate permissions:
chmod +x {{paperless_dir}}/backup-paperless.shFirst Test Run
Run the script once by hand before you automate it:
{{paperless_dir}}/backup-paperless.sh========================================================
Starting Paperless backup: Thu Nov 5 05:27:54 AM UTC 2026
========================================================
[+] Creating backup directory: /home/deployn/backup/2026-11-05_05-27-54
[+] Creating PostgreSQL dump...
-> Database dump successful.
[+] Starting document_exporter...
-> Document exporter executed successfully.
[+] Synchronizing documents...
-> No previous backup found. Creating full copy.
-> Documents synchronized.
[+] Updating 'latest' link.
[+] Deleting backups older than 30 days...
-> Cleanup complete.
========================================================
Paperless backup completed successfully!
========================================================On the second run, the script reports Previous backup found. Using hard links. This saves space: in my test, the first backup with 30 documents took 1.4 MB and the second only 516 KB, because unchanged files point to the first one via hard links. You can see the difference with du -sh:
du -sh {{backup_dir}}/*Important: The Export Path
The script assumes that you have defined a volume for the export in your compose.yaml. It should look roughly like this:
volumes:
- ./data:/usr/src/paperless/data
- ./media:/usr/src/paperless/media
- ./export:/usr/src/paperless/export # <--- IMPORTANT
- ./consume:/usr/src/paperless/consumeThe document_exporter command in the script (../export) refers to the path inside the container. Since Paperless often works in /usr/src/paperless/src inside the container, ../export leads to /usr/src/paperless/export, which we mapped to the outside.
Automation with Cron
Nobody likes making backups manually. Let’s set up a cron job that does this every night at 3 AM.
crontab -eAdd the following line (adjusted to your path):
0 3 * * * {{paperless_dir}}/backup-paperless.sh >> /var/log/paperless_backup.log 2>&1Or create a different schedule.
Restore: Disaster Recovery
A backup is worthless if you can’t restore it. Here is the way back if your server needs to be completely set up from scratch.
1. Prepare a Fresh Installation
Create a new Paperless directory with the same compose.yaml, as if it were a new server. Create the empty folders data, media, export, consume and db and start the complete stack, so database and web server:
docker compose up -d
docker compose psWait until the web server reports healthy. It creates the database tables while doing so.
2. Copy the Backup into the Export Folder
Copy the contents of documents from your backup into the export folder of the new installation. The dot at the end of documents/. is important so that the contents are copied and not the folder itself:
cp -r {{backup_dir}}/latest/documents/. export/3. Run the Importer
docker compose exec -T {{webserver_service}} document_importer ../export --no-progress-barFound existing user(s), this might indicate a non-empty installation
Checking the manifest
Copy files into paperless...
Updating search index...The first line is harmless if you created an admin user at startup (for example via PAPERLESS_ADMIN_USER). The importer reads the manifest.json, writes documents, tags, correspondents and users into the database, copies the files into media and rebuilds the search index.
Afterwards, the credentials from the backup apply. In my test, the admin user of the fresh installation had a different password than the one in the backup. After the import, only the old password worked.
Variant: Restore Only the Database from the SQL Dump
The dump in paperless-db.sql only contains the database, not the document files. It is useful if only the database is broken and the media folder is still there, or if you want to change the PostgreSQL version. For that, start only the database service with an empty database and load the dump:
docker compose up -d {{db_service}}
docker compose exec -T {{db_service}} psql -U {{db_user}} -d {{db_name}} -v ON_ERROR_STOP=1 < {{backup_dir}}/latest/paperless-db.sqlThe steps for a version change are in Paperless-ngx: Upgrade PostgreSQL to Version 18.
MariaDB Instead of PostgreSQL
Paperless-ngx also runs with MariaDB. Hardly anything changes here, because the Document Exporter and the importer work the same with both databases. If you only back up the export, you need no adjustment. If you also want an SQL dump, swap the line with pg_dump in the script:
${DOCKER_COMPOSE_CMD} exec -T "${DB_SERVICE}" pg_dump -U "${DB_USER}" -d "${DB_NAME}" > "${BACKUP_DIR}/paperless-db.sql"
${DOCKER_COMPOSE_CMD} exec -T "${DB_SERVICE}" sh -c 'mariadb-dump -h localhost -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"' > "${BACKUP_DIR}/paperless-db.sql"The line with sh -c reads user, password and database name from the environment variables of the database container (MARIADB_USER, MARIADB_PASSWORD, MARIADB_DATABASE). That way, no password is in the script. This requires that these variables are set on your db service in the compose.yaml, as in the official example. The variables DB_USER and DB_NAME in the script are then unused.
To load a dump, use the matching counterpart:
docker compose exec -T {{db_service}} sh -c 'mariadb -h localhost -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"' < {{backup_dir}}/latest/paperless-db.sqlThe restore with the importer (steps 1 to 3 above) stays unchanged.
Don’t Forget the 3-2-1 Rule
The script above stores the data locally in another folder. If your hard drive dies, the backup is gone too.
You should definitely copy the folder {{backup_dir}} to an external destination. You can do this with:
- Rclone (Upload to Google Drive, OneDrive, S3)
- BorgBackup (Encrypted backup to another server)
- Synology Hyper Backup (If you are on a NAS)
Switching the PostgreSQL Version
The database dump is also the way to move the database to a newer PostgreSQL version. The steps are in Paperless-ngx: Upgrade PostgreSQL to Version 18.
Conclusion
The script backs up database and documents in one run, and thanks to hard links, every further backup only takes the space of the changed files. When setting up, the service names in the compose.yaml matter most.
Make sure to test the restore process once in a virtual machine or on a test system before you rely on it in an emergency!
FAQ
Frequently asked questions
Is the Document Exporter alone enough as a backup?
For the restore, usually yes. Besides the documents, the export also contains the database content in the file manifest.json, and the importer restores both. The additional SQL dump is a safety net, for example for changing the database version.
Does the backup also work with MariaDB?
Yes. Exporter and importer are independent of the database. For an additional SQL dump, you swap pg_dump for mariadb-dump in the script. The MariaDB section above shows the necessary commands.
Can I make the backup while Paperless is running?
Yes. The dump and the Document Exporter work during operation.
Why is the second backup so much smaller than the first?
The script uses rsync with hard links. Files that did not change are not copied again but point to the file in the previous backup. In my test, it was 1.4 MB for the first and 516 KB for the second backup.
How do I check that my backup really works?
Restore it on a test server or in a virtual machine, as described in the restore section. Afterwards, compare the number of documents and log in with your credentials.
Changelog
Reworked the script: incomplete backups are removed on errors, restore with the importer rewritten. Added a section on MariaDB and an FAQ.