PhotoPrism - an AI-Powered Photos App for the Decentralized Web

Make use of the latest technologies to tag and find pictures automatically without getting in your way

PhotoPrism - an AI-Powered Photos App for the Decentralized Web

1. Background

PhotoPrism® is an AI-Powered Photos App for the Decentralized Web. It makes use of the latest technologies to tag and find pictures automatically without getting in your way. You can run it at home, on a private server, or in the cloud.

  • Browse all your photos and videos without worrying about RAW conversion, duplicates or video formats
  • Easily find specific pictures using powerful search filters
  • Recognizes the faces of your family and friends
  • Automatic classification of pictures based on their content and location
  • Play Live Photos by hovering over them in albums and search results
  • Since the User Interface is a Progressive Web App, it provides a native app-like experience, and you can conveniently install it on the home screen of all major operating systems and mobile devices
  • Includes four high-resolution World Maps to bring back the memories of your favorite trips
  • Metadata is extracted and merged from Exif, XMP, and other sources such as Google Photos
  • Many more image properties like Colors, Chroma, and Quality can be searched as well
  • Use PhotoSync to securely backup iOS and Android phones in the background
  • WebDAV clients such as Microsoft's Windows Explorer and Apple's Finder can connect directly to PhotoPrism, allowing you to open, edit, and delete files from your computer as if they were local
    GitHub Repo: PhotoPrism
    In this article, I will introduce the docker deployment of PhotoPrism, and some basic configuration post-installation.

2. PhotoPrism Configuration

  • Prerequisite
apt -y update
apt -y install curl nginx python3-certbot-nginx
curl -fsSL -o
  • Create docker-compose.yml
mkdir photoprism
cd photoprism
nano docker-compose.yml
version: '3.8'

# Example Docker Compose config file for PhotoPrism (Linux / AMD64)
# Note:
# - Hardware transcoding is only available for sponsors due to the high maintenance and support effort.
# - Running PhotoPrism on a server with less than 4 GB of swap space or setting a memory/swap limit can cause unexpected
#   restarts ("crashes"), for example, when the indexer temporarily needs more memory to process large files.
# - 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:
# Setup Guides:
# -
# -
# Troubleshooting Checklists:
# -
# -
# -
# CLI Commands:
# -
# All commands may have to be prefixed with "sudo" when not running as root.
# This will point the home directory shortcut ~ to /root in volume mounts.

    ## Use photoprism/photoprism:preview for testing preview builds:
    image: photoprism/photoprism:latest
    ## Don't enable automatic restarts until PhotoPrism has been properly configured and tested!
    ## If the service gets stuck in a restart loop, this points to a memory, filesystem, network, or database issue:
    restart: unless-stopped
    stop_grace_period: 10s
      - mariadb
      - seccomp:unconfined
      - apparmor:unconfined
      - "" # HTTP port (host:container)
      PHOTOPRISM_ADMIN_USER: "admin"                 # superadmin username
      PHOTOPRISM_ADMIN_PASSWORD: "insecure"          # initial superadmin password (8-72 characters)
      PHOTOPRISM_AUTH_MODE: "password"               # authentication mode (public, password)
      PHOTOPRISM_SITE_URL: ""  # server URL in the format "http(s)://"
      PHOTOPRISM_ORIGINALS_LIMIT: 5000               # file size limit for originals in MB (increase for high-res video)
      PHOTOPRISM_HTTP_COMPRESSION: "gzip"            # improves transfer speed and bandwidth utilization (none or gzip)
      PHOTOPRISM_LOG_LEVEL: "info"                   # log level: trace, debug, info, warning, error, fatal, or panic
      PHOTOPRISM_READONLY: "false"                   # do not modify originals directory (reduced functionality)
      PHOTOPRISM_EXPERIMENTAL: "false"               # enables experimental features
      PHOTOPRISM_DISABLE_CHOWN: "false"              # disables updating storage permissions via chmod and chown on startup
      PHOTOPRISM_DISABLE_WEBDAV: "false"             # disables built-in WebDAV server
      PHOTOPRISM_DISABLE_SETTINGS: "false"           # disables settings UI and API
      PHOTOPRISM_DISABLE_TENSORFLOW: "false"         # disables all features depending on TensorFlow
      PHOTOPRISM_DISABLE_FACES: "false"              # disables face detection and recognition (requires TensorFlow)
      PHOTOPRISM_DISABLE_CLASSIFICATION: "false"     # disables image classification (requires TensorFlow)
      PHOTOPRISM_DISABLE_RAW: "false"                # disables indexing and conversion of RAW images
      PHOTOPRISM_RAW_PRESETS: "false"                # enables applying user presets when converting RAW images (reduces performance)
      PHOTOPRISM_JPEG_QUALITY: 85                    # a higher value increases the quality and file size of JPEG images and thumbnails (25-100)
      PHOTOPRISM_DETECT_NSFW: "false"                # automatically flags photos as private that MAY be offensive (requires TensorFlow)
      PHOTOPRISM_UPLOAD_NSFW: "true"                 # allows uploads that MAY be offensive (no effect without TensorFlow)
      # PHOTOPRISM_DATABASE_DRIVER: "sqlite"         # SQLite is an embedded database that doesn't require a server
      PHOTOPRISM_DATABASE_DRIVER: "mysql"            # use MariaDB 10.5+ or MySQL 8+ instead of SQLite for improved performance
      PHOTOPRISM_DATABASE_SERVER: "mariadb:3306"     # MariaDB or MySQL database server (hostname:port)
      PHOTOPRISM_DATABASE_NAME: "photoprism"         # MariaDB or MySQL database schema name
      PHOTOPRISM_DATABASE_USER: "photoprism"         # MariaDB or MySQL database user name
      PHOTOPRISM_DATABASE_PASSWORD: "insecure"       # MariaDB or MySQL database user password
      PHOTOPRISM_SITE_CAPTION: "AI-Powered Photos App"
      PHOTOPRISM_SITE_DESCRIPTION: ""                # meta site description
      PHOTOPRISM_SITE_AUTHOR: ""                     # meta site author
      ## Run/install on first startup (options: update https gpu tensorflow davfs clitools clean):
      # PHOTOPRISM_INIT: "https gpu tensorflow"
      ## Hardware Video Transcoding:
      # PHOTOPRISM_FFMPEG_ENCODER: "software"        # FFmpeg encoder ("software", "intel", "nvidia", "apple", "raspberry")
      # PHOTOPRISM_FFMPEG_BITRATE: "32"              # FFmpeg encoding bitrate limit in Mbit/s (default: 50)
      ## Run as a non-root user after initialization (supported: 0, 33, 50-99, 500-600, and 900-1200):
      # PHOTOPRISM_UID: 1000
      # PHOTOPRISM_GID: 1000
      # PHOTOPRISM_UMASK: 0000
    ## Start as non-root user before initialization (supported: 0, 33, 50-99, 500-600, and 900-1200):
    # user: "1000:1000"
    ## Share hardware devices with FFmpeg and TensorFlow (optional):
    # devices:
    #  - "/dev/dri:/dev/dri"                         # Intel QSV
    #  - "/dev/nvidia0:/dev/nvidia0"                 # Nvidia CUDA
    #  - "/dev/nvidiactl:/dev/nvidiactl"
    #  - "/dev/nvidia-modeset:/dev/nvidia-modeset"
    #  - "/dev/nvidia-nvswitchctl:/dev/nvidia-nvswitchctl"
    #  - "/dev/nvidia-uvm:/dev/nvidia-uvm"
    #  - "/dev/nvidia-uvm-tools:/dev/nvidia-uvm-tools"
    #  - "/dev/video11:/dev/video11"                 # Video4Linux Video Encode Device (h264_v4l2m2m)
    working_dir: "/photoprism" # do not change or remove
    ## Storage Folders: "~" is a shortcut for your home directory, "." for the current directory
      # "/host/folder:/photoprism/folder"                # Example
      - "./Pictures:/photoprism/originals"               # Original media files (DO NOT REMOVE)
      # - "/example/family:/photoprism/originals/family" # *Additional* media folders can be mounted like this
      # - "~/Import:/photoprism/import"                  # *Optional* base folder from which files can be imported to originals
      - "./storage:/photoprism/storage"                  # *Writable* storage folder for cache, database, and sidecar files (DO NOT REMOVE)

  ## Database Server (recommended)
  ## see
    image: mariadb:10.11
    ## If MariaDB gets stuck in a restart loop, this points to a memory or filesystem issue:
    restart: unless-stopped
    stop_grace_period: 5s
    security_opt: # see
      - seccomp:unconfined
      - apparmor:unconfined
    command: mysqld --innodb-buffer-pool-size=512M --transaction-isolation=READ-COMMITTED --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --max-connections=512 --innodb-rollback-on-timeout=OFF --innodb-lock-wait-timeout=120
    ## Never store database files on an unreliable device such as a USB flash drive, an SD card, or a shared network folder:
      - "./database:/var/lib/mysql" # DO NOT REMOVE
      MARIADB_DATABASE: "photoprism"
      MARIADB_USER: "photoprism"
      MARIADB_PASSWORD: "insecure"
      MARIADB_ROOT_PASSWORD: "insecure"

  ## Watchtower upgrades services automatically (optional)
  ## see
  ## activate via "COMPOSE_PROFILES=update docker compose up -d"
    restart: unless-stopped
    image: containrrr/watchtower
    profiles: ["update"]
      WATCHTOWER_POLL_INTERVAL: 7200 # checks for updates every two hours
      - "/var/run/docker.sock:/var/run/docker.sock"
      - "~/.docker/config.json:/config.json" # optional, for authentication if you have a Docker Hub account
  • You have to change the following env values:
  • Bring up the container
docker compose up -d

3. Nginx Configuration

  • Create Nginx config file for PhotoPrism
nano /etc/nginx/conf.d/photoprism.conf
server {
    listen 80;
    client_max_body_size 0;

    location / {
       	proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
       	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  • Issue SSL cert
certbot –nginx
  • Restart Nginx service
nginx -t
systemctl restart nginx

4. Post-Deployment Setting

Go to your PhotoPrism web portal, with username admin and default password insecure. Important: Once you login, change the admin password immediately.
It’s strongly recommended to use upload tools to upload your media files, instead of uploading from local via web. In this article, I’ll show you one example, using Rclone to upload you media (photos and videos) from Google Drive to PhotoPrism.

  • For Rclone setups, you can refer to my previous article Upload Files from Server to Google Drive via Rclone
  • Once your Rclone configuration is done. You can upload media directly from Google Drive to PhotoPrism at a very high speed. This can save you huge amount of time if the total media size is big.
rclone copy google-drive:Your/Drive/Path/Awesome\ Album /Your/PhotoPrism/Path/Pictures

Note: Both paths have to be absolute paths. If your folder name contains space, please use \ to type in the linux command line since it uses regular expression.

  • In your PhotoPrism web portal, Library -> INDEX -> START. The process time varies, depending on your CPU performance, and it may take a while for large quantities.

Copyright statement: Unless otherwise stated, all articles on this blog adopt the CC BY-NC-SA 4.0 license agreement. For non-commercial reprints and citations, please indicate the author: Henry, and original article URL. For commercial reprints, please contact the author for authorization.