Set Up Photoprism as a Self-Hosted AI Photo Manager

Taking Back Control of Your Photo Library

Cloud photo services have a habit of changing the rules. Storage limits shrink, subscription prices climb, and somewhere buried in a terms-of-service update, your photos become training data for someone else’s AI model. PhotoPrism offers a different arrangement: a self-hosted photo management application that runs on your own hardware, uses machine learning to tag and organize images automatically, and keeps your library entirely under your control. It supports face recognition, object detection, and location mapping without phoning home to any third-party server.

Setting it up takes about 30 to 45 minutes if you have Docker already installed. The result is a polished, Google Photos-style web interface that works from any browser on your network – or over the internet if you configure remote access. This guide walks through the full installation using Docker Compose, including storage configuration, initial indexing, and the AI features that make PhotoPrism genuinely useful rather than just a fancy file browser.

What You Need Before Starting

PhotoPrism runs on Linux, macOS, and Windows via Docker. For a smooth experience, the host machine should have at least 2GB of RAM allocated to the container, though 4GB is more practical if your library runs into tens of thousands of photos. A modern CPU matters more than you might expect – the AI indexing pipeline is CPU-intensive, and older low-power hardware like a first-generation Raspberry Pi will struggle. A Raspberry Pi 4 with 4GB or 8GB of RAM works reasonably well. Any x86-64 machine from the last several years will handle it comfortably.

You need Docker and Docker Compose installed on the host. If you are running Ubuntu or Debian, sudo apt install docker.io docker-compose-plugin covers both packages. Confirm they are working with docker --version and docker compose version before proceeding. You also need a directory on the host where your original photos live – PhotoPrism mounts this as a read-only or read-write volume depending on how you configure it. Knowing that path ahead of time saves editing time later.

Installing PhotoPrism with Docker Compose

Create a working directory for the project. A clean location like /opt/photoprism works well on Linux. Inside that directory, create a file named docker-compose.yml. The official PhotoPrism repository provides a reference compose file, but the core structure is straightforward: two services, one for PhotoPrism itself and one for MariaDB, which handles the metadata database.

Paste the following into your compose file, adjusting the paths and passwords to match your setup:

services:
  photoprism:
    image: photoprism/photoprism:latest
    restart: unless-stopped
    ports:
      - "2342:2342"
    environment:
      PHOTOPRISM_ADMIN_USER: "admin"
      PHOTOPRISM_ADMIN_PASSWORD: "your-secure-password"
      PHOTOPRISM_AUTH_MODE: "password"
      PHOTOPRISM_SITE_URL: "http://localhost:2342/"
      PHOTOPRISM_ORIGINALS_LIMIT: 5000
      PHOTOPRISM_HTTP_COMPRESSION: "gzip"
      PHOTOPRISM_DATABASE_DRIVER: "mysql"
      PHOTOPRISM_DATABASE_SERVER: "mariadb:3306"
      PHOTOPRISM_DATABASE_NAME: "photoprism"
      PHOTOPRISM_DATABASE_USER: "photoprism"
      PHOTOPRISM_DATABASE_PASSWORD: "db-password"
    volumes:
      - /your/photos:/photoprism/originals
      - photoprism_storage:/photoprism/storage
    depends_on:
      - mariadb

  mariadb:
    image: mariadb:10.11
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: photoprism
      MARIADB_USER: photoprism
      MARIADB_PASSWORD: db-password
      MARIADB_ROOT_PASSWORD: root-password
    volumes:
      - mariadb_data:/var/lib/mysql

volumes:
  photoprism_storage:
  mariadb_data:

The /your/photos path on the left side of the originals volume mount is where PhotoPrism will read your actual image files. By default, this is mounted read-write, which allows PhotoPrism to write sidecar files alongside originals. If you prefer it to never touch your files, add :ro to make it read-only – PhotoPrism stores all metadata in the database instead. The photoprism_storage named volume holds thumbnails, the AI model files, and cached data, and it will grow significantly as your library indexes.

With the compose file saved, start the stack from inside the project directory with docker compose up -d. Docker pulls the images on first run, which takes a few minutes depending on your connection speed. Once containers are running, open a browser and navigate to http://your-host-ip:2342. Log in with the admin credentials you set. The interface loads immediately, but your photos are not yet visible – indexing is a separate step you trigger manually.

Running the First Index and Enabling AI Features

From the left sidebar, go to Library and then click Index. PhotoPrism will scan your originals folder, generate thumbnails, extract EXIF metadata, and run the AI analysis pipeline on every image. For a library of several thousand photos, this initial run takes anywhere from a few minutes to several hours. The AI component – which handles scene classification, color analysis, and quality scoring – runs on the CPU by default.

Face recognition is disabled by default for privacy reasons. To enable it, open Settings, go to the Features tab, and toggle Faces on. After re-indexing, PhotoPrism clusters detected faces and presents them in the People section of the sidebar. You can assign names to clusters, and the system learns from those labels to improve future matches. The accuracy is solid for clear, well-lit faces and degrades predictably with motion blur, extreme angles, or low resolution.

Accessing PhotoPrism Remotely and Keeping It Secure

Running PhotoPrism only on your local network is fine for home use, but remote access requires a few additional steps. The recommended approach is to put a reverse proxy in front of PhotoPrism – Caddy or Nginx Proxy Manager are both commonly used for this. The reverse proxy handles HTTPS termination using a Let’s Encrypt certificate, so the connection from your browser to the server is encrypted. PhotoPrism’s own HTTP connection between the proxy and the container stays on your local network and does not need to be secured separately.

If you run other self-hosted services alongside PhotoPrism, a unified dashboard makes navigation easier. Glance works well as a self-hosted at-a-glance dashboard that can link out to PhotoPrism and other services from a single browser tab. For the PhotoPrism container itself, set a strong admin password and consider enabling two-factor authentication under Settings – Account once you have remote access configured. The default port 2342 is not widely scanned by bots, but that is not a substitute for proper authentication.

WebDAV access is another useful feature worth enabling. PhotoPrism exposes a WebDAV endpoint that lets you connect from any WebDAV-compatible client – including the iOS and Android file managers – and upload photos directly into the originals folder. After uploading via WebDAV, trigger a new index from the Library menu and the photos appear in the interface within seconds. This makes mobile uploads practical without needing a dedicated mobile app.

Managing Your Library Long Term

PhotoPrism’s search syntax is one of its less obvious strengths. The search bar accepts filters like type:video, color:red, country:de, year:2022, and face:known. Combining these filters produces precise results that would require several clicks in most consumer apps. Searching quality:3 year:2023 country:jp returns only high-quality shots taken in Japan during 2023 – the kind of targeted retrieval that makes a large library actually navigable.

Album creation is manual but straightforward. PhotoPrism does not auto-generate albums the way Google Photos does, which some users find limiting. The tradeoff is that your organizational choices persist exactly as you make them, with no algorithm quietly rearranging things after a software update. For automated organization, the folder view reflects your original directory structure on disk, so maintaining a logical folder hierarchy in your originals directory doubles as your backup organizational system. If you ever stop using PhotoPrism, your files are exactly where you left them – no export process, no proprietary format to undo.