At a minimum, a backup of PhotoPrism Pro should include the files in your originals folder and a copy of the index database. We also recommend backing up the storage folder so that you don’t need to recreate any thumbnail or sidecar files, and your backup includes all config files, certificates, and customizations.
The easiest way to create a full backup is to back up your originals and storage folders with any standard file backup utility. Since PhotoPrism automatically creates daily index backups in the storage folder, your file backup will then also include recent database dumps. You can run the backup command first if you want the dump to be as current as possible.
Scheduled Backups
By default, PhotoPrism Pro automatically creates a daily backup of the index database at a random time and retains the 3 most recent dumps, removing older ones as new ones are created. Album metadata is also backed up to YAML files on the same schedule.
This works with both MariaDB and SQLite. The schedule, the number of backups to retain, and the type of backups can be changed with the following config options:
| Environment | Default | Description |
|---|---|---|
| PHOTOPRISM_BACKUP_SCHEDULE | daily | daily or weekly at a random time, or a schedule in cron format, e.g. 0 12 * * * for noon |
| PHOTOPRISM_BACKUP_RETAIN | 3 | number of index backups to keep (-1 to keep all) |
| PHOTOPRISM_BACKUP_DATABASE | true | enables regular index database backups |
| PHOTOPRISM_BACKUP_ALBUMS | true | enables the use of YAML files for backing up album metadata |
| PHOTOPRISM_BACKUP_PATH | custom base path for creating and restoring backups |
Schedules are based on the time zone configured with PHOTOPRISM_DEFAULT_TIMEZONE. No backups are created if PHOTOPRISM_DISABLE_BACKUPS is set to true, or if storage space is insufficient.
Scheduled backups are stored in the storage folder on the same disk as your index. They protect you against accidental changes and failed updates, but not against hardware failure, so make sure to also copy them to another disk or server.
Backup Folders
By default, index backups are saved as storage/backup/[driver]/[YYYY-MM-DD].sql, where [driver] is mysql for MariaDB and sqlite3 for SQLite, and the date is in UTC. A custom base folder can be configured with PHOTOPRISM_BACKUP_PATH.
Album YAML files are saved in storage/albums, if this folder exists, or storage/backup/albums otherwise.
Important Folders
Originals
The originals folder contains your original photo and video files. By default, it is located at /opt/photoprism/originals on the host server and at /photoprism/originals in the app container.
You can back it up and restore it using any standard file backup utility if you haven’t already set this up.
Storage
SQLite, config, cache, thumbnail, sidecar, and backup files are saved in the storage folder, which by default is located at /opt/photoprism/storage on the host server and at /photoprism/storage in the app container.
We recommend that you back up this folder as well so that you don’t need to recreate the thumbnails and have a complete backup of your configuration. As for the originals folder, you can use any standard file backup utility to do this.
If you use SQLite, backing up the storage folder is mandatory, as it also contains the index database files.
Backup Command
To manually create an index database backup, run this command in a terminal:
docker compose exec photoprism photoprism backup -i -f
If you are using Podman on a Red Hat-compatible Linux distribution:
podman-compose exec photoprism photoprism backup -i -f
The -f flag replaces an existing backup from the same day, e.g. one that was already created by a scheduled backup. Omit it if you do not want to overwrite existing files. Add the -a flag to also back up album metadata to YAML files.
You can also specify a custom filename as an argument:
docker compose exec photoprism photoprism backup -i [filename]
Backups with a custom filename that does not match the YYYY-MM-DD.sql pattern are not removed when older backups are cleaned up, so this is a good way to keep a backup before a major update, e.g. /photoprism/storage/backup/before-update.sql.
To write the dump to stdout instead, for example to save it outside the container, pass - as filename and run the command with the -T flag so that no log messages are included:
docker compose exec -T photoprism photoprism backup -i - > photoprism-db.sql
Note that our guides use the new docker compose command by default. If your server does not yet support it, the old docker-compose command will still work.
Users of Red Hat Enterprise Linux® and compatible Linux distributions such as CentOS, Fedora, AlmaLinux, and Rocky Linux can substitute the docker and docker compose commands with podman and podman-compose as drop-in replacements.
Restore Command
To restore the index from an existing database dump, you can run the following command:
docker compose exec photoprism photoprism restore -i -f
If you are using Podman on a Red Hat-compatible Linux distribution:
podman-compose exec photoprism photoprism restore -i -f
This will automatically search the backup folder for the most recent index dump and restore it. A custom backup folder can be configured with PHOTOPRISM_BACKUP_PATH.
Omit the -f flag to prevent overwriting an existing index. As with the backup command, you can also specify a specific dump filename as an argument, or - to read it from stdin:
docker compose exec photoprism photoprism restore -i [filename]
Add the -a flag to also restore albums from YAML files. If the index does not contain any albums yet, for example after starting with an empty database, they are also restored from these files automatically when PhotoPrism starts.
When the database is restored, all user accounts and passwords are restored as well. If users have changed their password, they will have to log in with their old password.
If you have a backup copy of your storage and originals folders, the easiest way is to restore those folders first and then run the restore command in case you are using MariaDB. Otherwise, you additionally need to perform a complete rescan of your library to recreate missing sidecar and thumbnail files. Some of the metadata and your albums can also be recovered from YAML sidecar files even if you don’t have a copy of the index database, unless you have disabled this feature.
PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
