Running PhotoPrism with Docker¶
We recommend using Docker Compose because it is easier and provides more convenience for running multiple services than the pure Docker command-line interface. Before you proceed, make sure you have Docker installed on your system. It is available for Mac, Linux, and Windows.
Step 1: Start the server¶
Open a terminal and run this command to start the app after replacing
the folder containing your pictures:
docker run -d \ --name photoprism \ --security-opt seccomp=unconfined \ --security-opt apparmor=unconfined \ -p 2342:2342 \ -e PHOTOPRISM_UPLOAD_NSFW="true" \ -e PHOTOPRISM_ADMIN_PASSWORD="insecure" \ -v /photoprism/storage \ -v ~/Pictures:/photoprism/originals \ photoprism/photoprism
The server port and other config options can be changed as needed. If you provide no database server credentials, SQLite database files will be created in the storage folder.
PHOTOPRISM_ADMIN_PASSWORD so that the app starts with a secure initial password.
Never use easy-to-guess passwords or default values like
insecure on publicly accessible servers.
There is no default in case no password was provided. A minimum length of 8 characters is required.
Commands on Linux may have to be prefixed with
sudo when not running as root.
Note that this will point the home directory shortcut
/root in volume mounts.
Kernel security modules such as AppArmor and SELinux have been reported to cause
When the app has been started, open the Web UI by navigating to http://localhost:2342/. You should see a login screen.
Sign in with the user
admin and the password configured via
You may change it on the account settings page.
Enabling public mode will disable authentication.
It can be helpful to keep Docker running in the foreground while debugging
so that log messages are displayed directly. To do this, omit the
-d parameter when restarting.
Should the server already be running, or you see no errors, you may have started it on a different host and/or port. There could also be an issue with your browser, ad blocker, or firewall settings.
It is not possible to change the password via
PHOTOPRISM_ADMIN_PASSWORD after the app has been
started for the first time. You may run
docker exec -ti photoprism photoprism passwd
in a terminal to change an existing password. You can also reset your database for a clean start.
Since the app is running inside a container, you have to explicitly mount the host folders you want to use. PhotoPrism won't be able to see folders that have not been mounted. That's an important security feature.
The originals folder contains your original photo and video files. They are mounted from
~/Pictures in the example
~ is a shortcut for your home directory.
If read-only mode is enabled, all features that require write permission to the originals folder
are disabled, e.g. WebDAV, uploading and deleting files. Run the app with
for this. You can mount a folder with the
:ro flag to make Docker block write operations as well.
SQLite, cache, session, thumbnail and sidecar files are created in the storage folder:
- a storage folder must always be mounted so that you do not lose these files after a restart or upgrade
- never configure the storage folder to be inside the originals folder unless the name starts with a
.to indicate that it is hidden
- we recommend placing the storage folder on a local SSD drive for best performance
- mounting symbolic links or using them inside the storage folder is currently not supported
Using our example, an anonymous volume is created and mounted as storage folder. You can mount a specific host folder instead, just as with originals, which is better for production environments.
Should you later want to move your instance to another host, the easiest and most time-saving way is to copy the entire storage folder along with your originals and database.
You may optionally mount an import folder from which files can be transferred to the originals folder in a structured way that avoids duplicates. Imported files receive a canonical filename and will be organized by year and month.
Step 2: Index your library¶
Ensure there is enough disk space available for creating thumbnails and verify filesystem permissions before starting to index: Files in the originals folder must be readable, while the storage folder including all subdirectories must be readable and writeable.
Open the Web UI, go to Library and click Start to start indexing your pictures.
While indexing, JPEG sidecar files may be created for originals in other formats such as RAW and HEIF. This is required for image classification, facial recognition, and for displaying them in a Web browser. Sidecar and thumbnail files will be added to the storage folder, so that your originals folder won't be modified.
Of course, you can continue using your favorite tools for processing RAW files, editing metadata, or importing new shots. Go to Library and click Start to update the index after files have been changed, added, or removed. This can also be automated using CLI commands and a scheduler.
Easy, isn't it?
Step 3: When you're done...¶
You can stop PhotoPrism and start it again using the following commands:
docker stop photoprism docker start photoprism
To remove the container completely:
docker rm -f photoprism
If your server runs out of memory, the index is frequently locked, or other system resources are running low:
- Try reducing the number of workers by setting
PHOTOPRISM_WORKERSto a reasonably small value, depending on the CPU performance and number of cores
- Make sure your server has at least 4 GB of swap space so that indexing doesn't cause restarts when memory usage spikes; RAW image conversion and video transcoding are especially demanding
- If you are using SQLite, switch to MariaDB, which is better optimized for high concurrency
- As a last measure, you can disable the use of TensorFlow for image classification and facial recognition
Other issues? Our troubleshooting checklists help you quickly diagnose and solve them.
photoprism help lists all commands and config options available in the current version:
docker exec -ti photoprism photoprism help
--help flag to see a detailed command description, for example:
docker exec -ti photoprism photoprism backup --help
Prefixing commands with
docker exec -ti [container name] runs them inside an app container.
If this fails with no container found, make sure the app has been started and
its container has the same name.
PhotoPrism's command-line interface is well suited for job automation using a scheduler.
|Display Config Values||
|Repeat Failed Migrations||
|Change Admin Password||
|Show User Management Commands||
|Show Facial Recognition Commands||
|Reset People & Faces||
|Transcode Videos to AVC||
docker exec -ti 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 "Full Rescan" and then clicking "Start".