How to Run PhotoPrism on the Raspberry Pi?

PhotoPrism is an open-source personal photo management system that makes it easy to organize and browse your photo collection. With PhotoPrism, you can tag, label, and find photos using the content in the images rather than file names or folder structures.

How to Run PhotoPrism on the Raspberry Pi?

The powerful search functionality, facial recognition, and mobile apps allow you to easily access specific photos and share memories. PhotoPrism also has built-in support for features like geo-location, color detection,Duplicate detection etc.

In this guide, we will walk through how to install and configure PhotoPrism on a Raspberry Pi. Using a Raspberry Pi as a low-power, always-on server is perfect for self-hosting an application like PhotoPrism.


Before we get started, you will need the following:

  • Raspberry Pi 3 B+ or newer
  • 8GB+ SD card
  • Power supply for Pi
  • Network connection via ethernet or WiFi
  • A domain name (or use the public IP)

We will be installing and configuring the following on the Pi:

  • Raspberry Pi OS
  • Docker & Docker Compose
  • PhotoPrism

I’ll also provide some tips on optimizing and customizing PhotoPrism to suit your needs.

Key Takeaway: A Raspberry Pi, SD card, power supply, and network connection are the key hardware requirements. The software we will install includes Raspberry Pi OS, Docker, Docker Compose, and PhotoPrism.

Step 1 – Setup Raspberry Pi

The first step is to get a baseline Raspberry Pi OS install with Docker and Docker Compose configured.

I recommend using the Raspberry Pi Imager to install the latest 64-bit Raspberry Pi OS to your SD card. Enable SSH in the imager so you can remote control your Pi.

Once you have Pi OS loaded and have booted your Pi, make sure to run sudo apt update && sudo apt full-upgrade to upgrade all packages.

Reboot, connect over SSH, and change the default password using the passwd command.

Install Docker and Docker Compose

Next, we’ll install Docker and Docker compose which will run the PhotoPrism container. Run the commands below:

curl -sSL | sh 

sudo usermod -aG docker pi

sudo systemctl enable docker

sudo apt install -y libffi-dev libssl-dev python3 python3-pip

sudo pip3 -v install docker-compose

Once Docker CE and docker-compose are installed, reboot your Pi for the changes to take effect.

Key Takeaway: Raspberry Pi OS should be installed with SSH enabled, packages upgraded, and the default password changed. Docker CE and Docker Compose also need to be installed before proceeding.

Step 2 – Deploy PhotoPrism

With Docker ready to go, we can now deploy a PhotoPrism container.

Create a directory that will be used to store the PhotoPrism data files and configurations:

mkdir ~/photoprism

Save the compose file below as photoprism.yml inside the ~/photoprism directory you created:


version: “3”



    image: photoprism/photoprism:latest

    restart: always


      – 2342:2342


      – ~/photoprism:/photoprism

      – /media/usb0:/photos


        PHOTOPRISM_DEBUG: “false”  

        PHOTOPRISM_PUBLIC: “true”

        PHOTOPRISM_WEB_SITE_BASE_URL: # Set your domain here

This compose file pulls the latest PhotoPrism image, exposes port 2342, mounts 2 volumes for persistent storage, and sets some environment variables like the base URL.

Now start the stack with:

cd ~/photoprism 

docker-compose up -d

Give the container about 60 seconds to fully initialize. Browse to your Pi server’s IP at port 2342 to create the admin account.

Key Takeaway: The steps covered deploying PhotoPrism via Docker Compose, initializing the application, and creating the admin account to get started.

Step 3 – Configure PhotoPrism

Once logged into PhotoPrism with your new admin account, there are a few key settings you should configure:

  1. General Settings: Set Dark mode if desired, change indexer speed from idle to low/medium if needed.
  2. Albums: Configure any default album trees you would like for organizing photos.
  3. Accounts: Add accounts for any users that require access besides admin.
  4. Sites: Create sites for your different storage locations, set the file path that was mounted in the compose file.
  5. Labels: Add default color labels categories you want applied to photos.

Now you can upload some test photos to the mounted USB drive and let PhotoPrism work its magic !

Key Takeaway: Key application settings to customize include layouts, albums, accounts, storage sites, labels and more before uploading media.

Advanced Configuration Tips

Here are some additional recommendations for optimizing and enhancing PhotoPrism on your Pi:

  • Attach storage via USB 3.0 ports for better performance
  • Change indexer speed to low/medium
  • Enable Go server workers if using Pi 4 for more cores
  • Lower thumbnail target size if limited space
  • Schedule background tasks through systemd
  • Automount network shares through fstab
  • Redirect HTTP to HTTPS
  • Setup trusted proxies for security
  • Automate imports from NAS/cloud storage
  • Integrate facial recognition

There are also many community contributed apps that enhance features like Maps, HEIC conversion, Raw processing, etc.

And since it’s open-source, you can even build customizations tailored to your needs!


In summary, self-hosting PhotoPrism on a Raspberry Pi provides an excellent private photo management system. It auto organizes your family memories while keeping all data under your control.

We walked through:

  1. Setting up a Raspberry Pi with Raspberry Pi OS and installing Docker
  2. Deploying PhotoPrism via Docker Compose
  3. Customizing key application settings
  4. Advanced tips for optimizations, enhancements, plugins, and more

PhotoPrism takes the work out of organizing your photo library. Features like facial recognition, location maps, color detection, and duplicates finder enable you to instantly find related photos.

Combined with the magic of the Raspberry Pi, you now have a low cost, low power server perfect for hosting PhotoPrism or any containerized application!


  1. How do I migrate from another platform?
    PhotoPrism makes migration easy with import from folders, Nextcloud, or common services. Export is also available into similar services.

  2. What to do on Raspberry Pi OS update?
    Check PhotoPrism changelog notes to see if Docker image updates are recommended. Run normal Pi OS updater first before PhotoPrism.

  3. Why are my previews and thumbs blurred?
    The image magick policies restrict certain formats from being processed. Update the environment configs to enable additional formats.

  4. How can I improve facial recognition?
    Enable raw pre-processing, increase indexer speed, train over time, augment with external face datasets, consider Intel Neural Compute stick.

  5. What causes missing thumbnails and sidecars?
    Often permission issues on mounted volumes, disable auto skip errors and check logs. Match user permissions across host OS and container.

  6. How do I password protect albums and share images?
    PhotoPrism albums fully support sharing album links with password protection as well as watermarked guest access.

  7. What are recommended specs for running PhotoPrism?
    For smaller libraries any SBC like Raspberry Pi will work. Larger professional libraries will benefit from more RAM, cores, SSD cache.

  8. Can I run PhotoPrism without Docker?
    Yes native binaries are provided for Linux, Mac, Windows that can be installed. Docker just simplifies environment and file paths.

  9. Why not use PiHole alongside PhotoPrism?
    Great combo as both prefer to be on 24/7. Be mindful of USB3 interference with WiFi or allocate ethernet port.

  10. What backup methods should I use?
    Leverage built-in Google Photos & Backblaze B2 integration. Or setup a cron job to rsync your storage volume to a NAS.

  11. How do I put PhotoPrism behind Nginx proxy?
    Update the PHOTOSPRISM config values for hostname. Configure Nginx proxy pass to route domain name to PhotoPrism container port.

  12. What is the best way to structure album hierarchy?
    Start broad ie. Places, People, Events, Years etc. PhotoPrism makes it easy to relocate photos so don’t overthink folder structures.

  13. Can I run PhotoPrism without Internet access?
    Yes fully works offline. Some features like maps for Geo locate require offline packages installed. Facial recognition models also need downloaded at least once.

  14. How can I exclude folders from indexing?
    Use the web UI Settings to configure paths to Exclude from indexing. This ensures they do not show in search results or albums views.

  15. What is difference between Darktable and PhotoPrism?
    Darktable great for editing while PhotoPrism more for organization. They have some overlapping RAW processing features. Can use together!

  16. How do I import photos spread across multiple drives?
    When configuring Sites, use same Site Name on multiple volumes. New files detected during index will be added automatically.

  17. Can PhotoPrism run well on budget Pi like the Pi Zero?
    Yes it can work but limited by the lower CPU and memory. Indexing times will be longer so run at idle/low priority. Enable Go workers for help.

  18. What causes excess CPU or RAM usage?
    Sometimes overly complex or larger images trigger CPU spikes. Lower quality previews helps ie. 200p thumbnails vs 500p. Processing RAWs also memory intensive.

  19. I only want to run this part time to save power?
    You can stop the Docker container temporarily during periods of low usage. Just be aware re-indexing takes time on restart.

  20. How do I submit feedback or features requests?
    The project is open source on GitHub. Feel free to create issues for bugs or feature requests. There is also community forum.for discussions!

Leave a Comment