Skip to content

Running PhotoPrism on a Raspberry Pi

Our stable version and development preview have been built into a single multi-arch Docker image for 64-bit AMD, Intel, and ARM processors.

That means, Raspberry Pi 3 / 4, Apple M1, and other ARM64-based devices can pull from the same repository, enjoy the exact same functionality, and can follow the regular Installation Instructions after going through a short list of System Requirements and Architecture Specific Notes.

Existing users are advised to keep their docker-compose.yml config updated based on the examples available at dl.photoprism.app/docker.

You are welcome to ask for help in our community chat. Sponsors receive direct technical support via email. Before submitting a support request, try to determine the cause of your problem.

System Requirements

  • Your device should have at least 4 GB of memory. Running PhotoPrism on a server with less than 4 GB of swap space or setting a memory/swap limit can cause unexpected restarts, especially when the indexer temporarily needs more memory to process large files.
  • We recommend disabling kernel security in your docker-compose.yml, especially if you do not have experience with the configuration:
    photoprism:
      security_opt:
        - seccomp:unconfined
        - apparmor:unconfined
    
  • If you install PhotoPrism on a public server outside your home network, please always run it behind a secure HTTPS reverse proxy such as Traefik or Caddy. Your files and passwords will otherwise be transmitted in clear text and can be intercepted by anyone, including your provider, hackers, and governments.

Indexing large photo and video collections significantly benefits from local SSD storage and plenty of memory for caching. Especially the conversion of RAW images and the transcoding of videos are very demanding.

If your server runs out of memory, the index is frequently locked, or other system resources are running low while indexing, you should try reducing the number of workers by setting PHOTOPRISM_WORKERS to a reasonably small value in docker-compose.yml (depending on the performance of the server). As a measure of last resort, you may disable using TensorFlow for image classification and facial recognition.

Architecture Specific Notes

Modern ARM64-based Devices

Image Name
Stable Release photoprism/photoprism:latest
Development Preview photoprism/photoprism:preview
MariaDB arm64v8/mariadb:10.6
Raspberry Pi OS

To ensure compatibility with 64-bit Docker images, your Raspberry Pi 3 / 4 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 arm_64bit=1 flag 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 linux/arm64.

In case you see Docker errors related to "cgroups", try adding the following parameters to /boot/firmware/cmdline.txt:

cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1
Raspbian Alternatives

Raspberry Pi OS is designed to be compatible with older 32-bit software. We recommend choosing a standard 64-bit Linux distribution to run modern server applications, for example:

Older ARMv7-based Devices

You have to resort to alternative Docker images to run PhotoPrism and MariaDB on ARMv7-based devices and those with a 32-bit operating system:

Image Name
ARMv7 Release photoprism/photoprism:armv7
MariaDB linuxserver/mariadb:latest

If your device meets the requirements, mostly the same installation instructions as for regular Linux servers apply. Pay close attention to changed directory and environment variable names.

Darktable is not included in the ARMv7 version because it is not 32-bit compatible.

Is a Raspberry Pi fast enough?

This largely depends on your expectations and the number of files you have. Most users report that PhotoPrism runs smoothly on their Raspberry Pi 4. However, initial indexing typically takes much longer than on standard desktop computers.

Also keep in mind that the hardware has limited video transcoding capabilities, so the conversion of video file formats is not well-supported and software transcoding is generally slow.

Getting Updates

Open a terminal and change to the folder where the docker-compose.yml file is located.1 Now run the following commands to download the most recent 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.

Advanced users can add this to a Makefile so that they only have to type a single command like make update. See Command-Line Interface to learn more about terminal commands.

Running an image with :latest tag does not cause Docker to automatically download new images.

Credits

A big thank you to Guy Sheffer for helping us build a Raspberry Pi version!


  1. The default Docker Compose config filename is docker-compose.yml. For simplicity, it doesn't need to be specified when running the docker-compose command in the same directory. Config files for other apps or instances should be placed in separate folders.