PhotoPrism Docker Deployment: An AI Photo Library in Three Steps

PhotoPrism is written in Go and excels at turning a chaotic photo archive into something searchable: AI labels, face clustering, place maps and RAW previews are all mature. This guide deploys it with the official Docker image on a 2 vCPU / 4 GB machine.

1. Who it is for

If you have a drive full of photos from the last fifteen years and want to "drop it in and search by person, place or content", PhotoPrism is more focused on curation than Immich. If you want photos uploaded automatically from your phone, Immich is the better fit. The two can happily coexist.

2. Image and directory layout

Item	Value
Image	photoprism/photoprism:latest (Docker Hub)
Web port	2342
Originals	./originals → /photoprism/originals
Import folder	./import → /photoprism/import
Storage	./storage → /photoprism/storage

SQLite is the default and handles tens of thousands of photos. Move to MariaDB beyond 100k photos or with several concurrent users.

3. Deploy with Compose

mkdir -p /opt/photoprism && cd /opt/photoprism
mkdir -p originals import storage

Create docker-compose.yml:

services:
  photoprism:
    image: photoprism/photoprism:latest
    container_name: photoprism
    restart: unless-stopped
    ports:
      - "2342:2342"
    environment:
      PHOTOPRISM_ADMIN_USER: "admin"
      PHOTOPRISM_ADMIN_PASSWORD: "replace-with-a-strong-password"
      PHOTOPRISM_SITE_URL: "https://photos.example.com/"
      PHOTOPRISM_SITE_TITLE: "Family Photos"
      PHOTOPRISM_SITE_CAPTION: "Our Family Photos"
      PHOTOPRISM_DEFAULT_LOCALE: "en"
      PHOTOPRISM_ORIGINALS_LIMIT: 100000
      PHOTOPRISM_HTTP_COMPRESSION: "gzip"
      PHOTOPRISM_LOG_LEVEL: "info"
      TZ: "Asia/Shanghai"
      # Write files as the host user to avoid permission problems
      PHOTOPRISM_UID: 1000
      PHOTOPRISM_GID: 1000
    working_dir: "/photoprism"
    volumes:
      - "./originals:/photoprism/originals"
      - "./import:/photoprism/import"
      - "./storage:/photoprism/storage"

docker compose up -d
docker compose logs -f photoprism

Open http://SERVER_IP:2342 and sign in as admin with the password you set.

4. Import and index

1. Copy photos into ./originals (keeping the folder structure), or upload/import through the web UI.
2. Run indexing so PhotoPrism generates thumbnails, EXIF data, locations and AI labels:

docker compose exec photoprism photoprism index
# Process only new photos
docker compose exec photoprism photoprism index --cleanup

Indexing tens of thousands of photos takes a long time; run it overnight and watch progress under Library → Index.

5. Reverse proxy and HTTPS

server {
    listen 443 ssl http2;
    server_name photos.example.com;

    ssl_certificate     /etc/letsencrypt/live/photos.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/photos.example.com/privkey.pem;

    client_max_body_size 2000M;

    location / {
        proxy_pass http://127.0.0.1:2342;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

6. Backup and upgrades

• Backup: originals (the photos) plus storage (database, thumbnails, settings). Backing up only originals loses albums, labels and faces.
• Upgrade: docker compose pull && docker compose up -d. Read the release notes first and follow the upgrade guide across major versions.
• Migration: copy the three directories to the new host and start the same Compose file.

7. Troubleshooting

Photos show "no permission" or thumbnails fail? The container UID does not match the host file owner. Run sudo chown -R 1000:1000 originals import storage, or set PHOTOPRISM_UID/GID to your user.

How do I change the interface language? PHOTOPRISM_DEFAULT_LOCALE only sets the default; users can switch it in their own settings.

Should I use MariaDB? SQLite is fine for one person with tens of thousands of photos. Switch when several people search concurrently or the library exceeds 100k — the migration is not hard.

8. Wrap-up

PhotoPrism's strength is curation, not automatic backup. Point it at your old photo drive, run one index, and years of pictures become visible again by person, place and content.

Related: Immich tutorial · 2026 self-hosted album comparison