Introduction

photoprism help lists all commands and config options available in the current version:

docker compose exec photoprism photoprism help

Use the --help flag to see a detailed command description, for example:

docker compose exec photoprism photoprism backup --help

PhotoPrism's command-line interface is also well suited for job automation e.g. using a scheduler.

When using Docker Compose, you can prefix the commands you want to run with docker compose exec [service] to execute them in the specified service container. If this fails with no container found, please make sure that the service has been started, you have specified an existing service (usually photoprism) and you are in the folder where your compose.yaml or docker-compose.yml file is located.

Opening a Terminal

To open a terminal session as the default user:

docker compose exec photoprism bash

Since the above will open the terminal as root by default, we recommend that you pass the -u flag to explicitly open a non-root session if PhotoPrism is running under a specific user account, for example:

docker compose exec -u 1000 photoprism bash

This avoids potential filesystem permission issues that can occur when a command creates new files or folders, e.g. to store thumbnails.

Changing the User ID

Specifying a user with the -u flag is possible for all commands you run with Docker and Docker Compose. In the following examples, it is omitted for brevity. Note, however, that commands that you run without an explicit user ID might be executed as root. The currently supported user ID ranges are 0, 33, 50-99, 500-600, 900-1250, and 2000-2100.

We recommend running the photoprism service as a non-root user by setting either the user service property or the PHOTOPRISM_UID environment variable in your compose.yaml or docker-compose.yml file. Don't forget to update file permissions and/or ownership with the chown command when you make changes.

Examples

Action Command
Start Services docker compose up -d
Stop Services docker compose stop
Download Updates docker compose pull
Uninstall docker compose rm -s -v
Watch Logs docker compose logs -f --tail=100
Display Config Values docker compose exec photoprism photoprism show config
Show Migration Status docker compose exec photoprism photoprism migrations ls
Repeat Failed Migrations docker compose exec photoprism photoprism migrations run -f
Reset Database docker compose exec photoprism photoprism reset --yes
Backup Database docker compose exec photoprism photoprism backup -a -i
Restore Database docker compose exec photoprism photoprism restore -a -i
Change Password docker compose exec photoprism photoprism passwd [username]
Remove Password docker compose exec photoprism photoprism passwd --rm [username]
Show User Management Commands docker compose exec photoprism photoprism users help
Reset User Accounts docker compose exec photoprism photoprism users reset --yes
Reset Sessions and Access Tokens docker compose exec photoprism photoprism auth reset --yes
Show Face Recognition Commands docker compose exec photoprism photoprism faces help
Index Faces docker compose exec photoprism photoprism faces index
Reset People & Faces docker compose exec photoprism photoprism faces reset -f
Transcode Videos to AVC docker compose exec photoprism photoprism convert
Regenerate Thumbnails docker compose exec photoprism photoprism thumbs -f
Update Index docker compose exec photoprism photoprism index --cleanup
Move to Originals docker compose exec photoprism photoprism import [path]
Copy to Originals docker compose exec photoprism photoprism cp [path]

Note that our examples use the new docker compose command by default. If your server does not yet support it, you can still use docker-compose or alternatively podman-compose on Red Hat-compatible Linux distributions.

docker compose exec photoprism photoprism index -f rescans all originals, including already indexed and unchanged files. This may be necessary after major upgrades and after migrations of the database schema, especially if search results are missing or incorrect. Note you can also start a rescan from the user interface by navigating to Library > Index, checking "Complete Rescan" and then clicking "Start". Manually entered information such as labels, people, titles or descriptions will not be modified when indexing, even if you perform a "complete rescan".

PhotoPrism® Documentation

For detailed information on specific product features, services, and related resources, see our Knowledge Base, or read the User Guide for help using the web user interface: