For your peace of mind, Papermerge provides easy way to backup/export and restore all your documents. Terms backup and export (similar for restore/import) are synonymous so they will be use here interchangeably.
To backup all document in Papermerge (for all users):$ ./manage.py backup
To restore given backup:$ ./manage.py restore <path-to-tar-file>
Backup does not save users’ passwords unless option
--include-user-password is specified. For papermerge system-wide
backups created without
--include-user-password option after restoring
the backup, system administrator need to set superuser password with
./manage changepassword command. Superuser in turn, will need to set
passwords for other Papermerge accounts.
System-wide or Per User?¶
There are at two different backup strategies:
- System-wide - will backup/restore all documents of all users in Papermerge instance
- Per User - will backup/restore all documents only for specific user
You can opt for per user backup strategy with
--user <username> switch.
If backup file was created with
--user <username> switch, it must be restored with same
--user <username>. If you forget to add
./manage.py restore command will
complain with an error.
Term system-wide here refers to Papermerge system - which is same as saying for all users in Papermerge database. Don’t confuse usage of term system here with operating system, or Linux system.
Per user backup strategy is very convenient when there is only one user in Papermerge. This strategy will backup all documents and preserve their folder structure. No user information will be stored in backup file.
System-wide (for all accounts in Papermerge) strategy will backup data per
each user in Papermerge instance. Along with documents, it will save
information like username, email and if that user is superuser or not. Note
however that users’s passwords won’t be saved unless you explicitely ask for
To create a backup of all documents currently found your in Papermerge instance, just run:
This will create a file backup_<current-datetime>.tar in same folder where manage.py file is located.
You can provide a file name as well:
./manage.py backup papermerge.tar
Notice tar extension. You can provide any file name (or path to a file) but keep in mind that backup command creates a tar archive for you.
Finally you can provide as argument an existing directory:
./manage.py backup /data/backups/papermerge/
In example above, file named /data/backups/papermerge/backup_<current-datetime>.tar will be created.
Before restoring a system-wide backup, please make sure that MEDIA_DIR is empty and you don’t have any user account created i.e. your Papermerge system was just freshly installed.
To restore documents from tar archive, use following command:
./manage.py restore <path-to-tar-file>
As main argument for restore command use provide path to tar archive.
Keep in mind that restore command expects tar archive - not zipped tar archive. In case your backup solution pipeline compressed tar archive provided by backup command - you will need to first uncompress it manually, and then provide it as argument to restore command.
Example of usage:
./manage.py restore papermerge_13_07_2020.tar
Because system-wide backups don’t store users passwords, you will need to set superuser password anew:
$ ./manage changepassword <superuser-username>