Running PhotoPrism on a Raspberry Pi¶
Our stable releases and preview builds are available as multi-arch Docker images for 64-bit AMD, Intel, and ARM processors.1 As a Raspberry Pi owner, you therefore get the exact same functionality and can follow the same installation steps after going through a short list of system requirements and architecture specific notes.
The easiest way to run PhotoPrism on a Raspberry Pi2 is with PhotoPrismPi. Simply flash the image to an SD card, plug it into the Pi and boot it. After a few minutes, our latest release will be ready to use!
- For a good user experience, we recommend running PhotoPrism on a Raspberry Pi 4 or 5 with at least 4 GB RAM and a 64-bit operating system
- High-resolution panoramic images may require additional swap space and/or physical memory above the recommended minimum
- Indexing performance will benefit greatly from using SSD storage, e.g. connected via USB 3
- Note that if less than 4 GB of swap space is configured or a manual memory/swap limit is set, this can cause unexpected restarts, for example, when the indexer temporarily needs more memory to process large files; RAW image conversion and TensorFlow are disabled on systems with 1 GB or less memory
- You should enable HTTPS or run your server behind a secure HTTPS reverse proxy like Traefik if it is connected to a shared network or the public Internet
- Depending on the Linux distribution, you may need to set the following security options in your docker-compose.yml:
photoprism: security_opt: - seccomp:unconfined - apparmor:unconfined
Architecture Specific Notes¶
Modern ARM64-based Devices¶
Running 64-bit Docker images under Raspbian Linux requires a minimum of technical experience to perform the necessary configuration changes. This is because it is a 32-bit operating system with merely a 64-bit kernel to ensure compatibility with legacy software. If you don't need compatibility with 32-bit apps, we recommend choosing a standard 64-bit Linux distribution instead as it will save you time and requires less experience:
- Raspberry Pi Debian
- Ubuntu for Raspberry Pi
- UbuntuDockerPi is a 64-bit Ubuntu Server with Docker pre-configured
Other distributions that target the same use case as Raspbian, such as CoreELEC, will have similar issues and should therefore also be avoided to run modern server applications.
Raspberry Pi OS¶
To ensure compatibility with 64-bit Docker images, your Raspberry Pi must boot with the
arm_64bit=1 flag in its config.txt file.
An "exec format" error will occur otherwise.
Try explicitly pulling the ARM64 version if you've booted your device with the
and you see the "no matching manifest" error on Raspberry Pi OS (Raspbian):
docker pull --platform=arm64 photoprism/photoprism:latest
It may also help to set the
DOCKER_DEFAULT_PLATFORM environment variable to
In case you see Docker errors related to "cgroups", try adding the following parameters to
/boot/cmdline.txt (file location depends on the OS in use):
cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1
Older ARMv7-based Devices¶
You may use the following 32-bit Docker images to run PhotoPrism and MariaDB on ARMv7-based devices (always use our ARM64 image if possible):
If your device meets the requirements, mostly the same installation instructions as for regular Linux servers apply. However, you should pay close attention to differences in path and environment variable names.
Darktable is not included in the ARMv7 image because it is not 32-bit compatible. Always choose the regular 64-bit version if your device supports it.
Is a Raspberry Pi fast enough?¶
This mainly depends on your expectations and the number of files you have. Most users report that PhotoPrism runs smoothly on a Raspberry Pi 4 with 4 GB of RAM.
Note, however, that initial indexing usually takes much longer than on a regular desktop computer and that the hardware has limited video transcoding capabilities, so video file format conversion is not well supported and software transcoding is generally slow. We take no responsibility for instability or performance problems if your device does not meet the requirements.
Open a terminal and change to the folder where the
docker-compose.yml file is located.3
Now run the following commands to download the newest image from Docker Hub and
restart your instance in the background:
docker compose pull
docker compose stop
docker compose up -d
Pulling a new version can take several minutes, depending on your internet connection speed.
Even when you use an image with the
:latest tag, Docker does not automatically download new images for you. You can either manually upgrade as shown above, or set up a service like Watchtower to get automatic updates.
Our config examples are generally based on the latest stable release to take advantage of performance enhancements. This does not mean older versions are no longer supported and you have to upgrade immediately.
If MariaDB fails to start after upgrading from an earlier version (or migrating from MySQL), the internal management schema may be outdated. See Troubleshooting MariaDB Problems for instructions on how to fix this.
If your device 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 in
docker-compose.yml, depending on the performance of your device
- Make sure your device 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.
Experienced users can alternatively use the packages at dl.photoprism.app/pkg/linux/ to manually install PhotoPrism on compatible Linux distributions. For more installation methods, see our Getting Started FAQ. ↩
The default Docker Compose config filename is
docker-compose.yml. For simplicity, it doesn't need to be specified when running
docker-composein the same directory. Config files for other apps or instances should be placed in separate folders. ↩