Photos intermediate ⏱ 60 minutes

PhotoPrism: AI-Powered Photo Management

Google Photos alternative with ML features. Face recognition, location, and powerful search.

By Homelab Team • 2025-01-15
#photoprism#photos#ai#machine-learning#docker

Introduction

PhotoPrism is a modern, AI-powered photo management application that brings the power of machine learning to your self-hosted photo library. Unlike traditional photo galleries, PhotoPrism automatically indexes, tags, and organizes your photos using advanced computer vision algorithms, making it easy to find any photo through natural language search.

Why Choose PhotoPrism?

Privacy-First AI Processing

All AI processing happens locally on your hardware. Your photos never leave your infrastructure, and there’s no cloud dependency for features like face recognition, object detection, or automatic tagging.

Intelligent Organization

PhotoPrism analyzes your photos to detect faces, objects, colors, and locations. It can recognize over 10,000 different objects, from “Golden Retriever” to “Eiffel Tower,” making your photo library searchable without manual tagging.

Professional-Grade Features

  • Automatic photo indexing and metadata extraction
  • Face detection and recognition
  • Object and scene detection
  • Color analysis and clustering
  • Geolocation and mapping
  • Duplicate detection
  • RAW image support for professional photographers
  • WebDAV integration for mobile apps

Cost Comparison

Compared to cloud services like Google Photos Premium ($9.99/month) or Adobe Creative Cloud with Lightroom ($19.99/month), PhotoPrism’s one-time setup cost pays for itself within months while offering comparable or superior features.

PhotoPrism vs. Alternatives

FeaturePhotoPrismImmichPiwigo
AI TaggingExcellentGoodNone
Face RecognitionYesYesPlugin
RAW SupportExcellentGoodLimited
Mobile AppsWebDAVNativeNative
Resource UsageMedium-HighMediumLow
Learning CurveModerateEasyEasy

Prerequisites

Before deploying PhotoPrism, ensure you have:

Hardware Requirements

Minimum Configuration:

  • CPU: 2 cores (4+ recommended for faster indexing)
  • RAM: 4GB (8GB+ recommended for large libraries)
  • Storage: 100GB+ free space (depends on library size)
  • GPU: Optional but highly recommended for ML acceleration

Recommended Configuration:

  • CPU: Intel i5/i7 or AMD Ryzen 5/7 (4+ cores)
  • RAM: 16GB
  • Storage: 2TB+ in RAID configuration
  • GPU: NVIDIA GPU with 4GB+ VRAM for TensorFlow acceleration

Software Requirements

  • Docker Engine 20.10 or newer
  • Docker Compose v2.0 or newer
  • Linux (Ubuntu 22.04 LTS, Debian 12, or similar)
  • Basic understanding of command line operations

Network Requirements

  • Static IP address or DHCP reservation
  • Reverse proxy setup (Traefik, Nginx Proxy Manager, or Caddy)
  • Optional: Domain name for remote access
  • Firewall configured to allow web traffic

Installation

Step 1: Create Directory Structure

First, create directories for PhotoPrism’s data:

# Create main PhotoPrism directory
mkdir -p ~/photoprism
cd ~/photoprism

# Create subdirectories
mkdir -p storage/{originals,import,sidecar,cache}
mkdir -p database
mkdir -p config

# Set proper permissions
chmod -R 755 storage
chmod 700 database

Directory Explanation:

  • originals: Your main photo library
  • import: Temporary location for new photos
  • sidecar: JSON files with extracted metadata
  • cache: Thumbnails and processed images
  • database: MariaDB data files

Step 2: Create Docker Compose Configuration

Create a docker-compose.yml file with the following content:

version: '3.8'

services:
  photoprism:
    image: photoprism/photoprism:latest
    container_name: photoprism
    restart: unless-stopped
    security_opt:
      - seccomp:unconfined
      - apparmor:unconfined
    ports:
      - "2342:2342"
    environment:
      # Initial Setup
      PHOTOPRISM_ADMIN_USER: "admin"
      PHOTOPRISM_ADMIN_PASSWORD: "ChangeThisPassword123"
      PHOTOPRISM_SITE_URL: "http://YOUR-SERVER-IP:2342/"
      PHOTOPRISM_SITE_TITLE: "My PhotoPrism"
      PHOTOPRISM_SITE_CAPTION: "Browse Your Life"

      # Database Configuration
      PHOTOPRISM_DATABASE_DRIVER: "mysql"
      PHOTOPRISM_DATABASE_SERVER: "mariadb:3306"
      PHOTOPRISM_DATABASE_NAME: "photoprism"
      PHOTOPRISM_DATABASE_USER: "photoprism"
      PHOTOPRISM_DATABASE_PASSWORD: "SecureDBPassword123"

      # Feature Flags
      PHOTOPRISM_READONLY: "false"
      PHOTOPRISM_EXPERIMENTAL: "false"
      PHOTOPRISM_DISABLE_CHOWN: "false"
      PHOTOPRISM_DISABLE_WEBDAV: "false"
      PHOTOPRISM_DISABLE_SETTINGS: "false"
      PHOTOPRISM_DISABLE_TENSORFLOW: "false"
      PHOTOPRISM_DISABLE_FACES: "false"
      PHOTOPRISM_DISABLE_CLASSIFICATION: "false"

      # Performance Settings
      PHOTOPRISM_WORKERS: "2"
      PHOTOPRISM_JPEG_QUALITY: "90"
      PHOTOPRISM_THUMB_FILTER: "lanczos"
      PHOTOPRISM_THUMB_SIZE: "2048"
      PHOTOPRISM_THUMB_SIZE_UNCACHED: "7680"

      # Optional: GPU Acceleration (uncomment if NVIDIA GPU available)
      # PHOTOPRISM_TENSORFLOW_MODE: "gpu"

    volumes:
      - "./storage/originals:/photoprism/originals"
      - "./storage/import:/photoprism/import"
      - "./storage/sidecar:/photoprism/storage/sidecar"
      - "./storage/cache:/photoprism/storage/cache"
    depends_on:
      - mariadb

  mariadb:
    image: mariadb:11
    container_name: photoprism-mariadb
    restart: unless-stopped
    security_opt:
      - seccomp:unconfined
      - apparmor:unconfined
    command: >
      --innodb-buffer-pool-size=1G
      --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
    environment:
      MARIADB_AUTO_UPGRADE: "1"
      MARIADB_INITDB_SKIP_TZINFO: "1"
      MARIADB_DATABASE: "photoprism"
      MARIADB_USER: "photoprism"
      MARIADB_PASSWORD: "SecureDBPassword123"
      MARIADB_ROOT_PASSWORD: "RootPassword456"
    volumes:
      - "./database:/var/lib/mysql"

networks:
  default:
    name: photoprism-network

Important: Change the following values:

  • PHOTOPRISM_ADMIN_PASSWORD: Use a strong password
  • PHOTOPRISM_DATABASE_PASSWORD and MARIADB_PASSWORD: Must match
  • MARIADB_ROOT_PASSWORD: Use a strong root password
  • PHOTOPRISM_SITE_URL: Use your actual server IP or domain

Step 3: Deploy PhotoPrism

Start the containers:

# Pull images and start services
docker compose up -d

# Monitor startup logs
docker compose logs -f photoprism

# Wait for initialization (first startup takes 2-3 minutes)
# Look for: "server has been started"

Verify containers are running:

docker compose ps

You should see both photoprism and photoprism-mariadb with status “Up”.

Step 4: Initial Configuration

Navigate to http://YOUR-SERVER-IP:2342 in your web browser.

  1. Log in with credentials:

    • Username: admin
    • Password: The password you set in docker-compose.yml

  2. Complete initial setup wizard:

    • Set your timezone
    • Configure library settings
    • Choose indexing options
    • Set up face recognition

  3. Change admin password:

    • Navigate to Settings (gear icon)
    • Go to Account Settings
    • Click “Change Password”
    • Use a strong, unique password

Photo Import and Organization

The import directory is designed for temporary staging of new photos:

# Copy photos to import directory
cp -r /path/to/new/photos/* ~/photoprism/storage/import/

# Or use rsync for large transfers
rsync -av --progress /path/to/new/photos/ ~/photoprism/storage/import/

In PhotoPrism web interface:

  1. Navigate to Library (folder icon)
  2. Click “Import”
  3. Select photos to import
  4. Click “Import X Files”

Photos are moved from import to originals and indexed automatically.

Method 2: Direct to Originals (For Existing Libraries)

For importing large existing photo libraries:

# Copy existing library
cp -r /media/photos/* ~/photoprism/storage/originals/

# Or mount existing storage
# Edit docker-compose.yml volumes section:
# - "/mnt/nas/photos:/photoprism/originals:ro"

Trigger indexing in web interface:

  1. Library > Index
  2. Choose options:
    • Complete Rescan: Full re-index
    • Skip Existing: Only new files
  3. Click “Start”

Organizing with Albums and Folders

Folder Structure:

PhotoPrism respects your folder organization:

originals/
├── 2023/
│   ├── 01-January/
│   ├── 02-February/
│   └── 12-December/
├── 2024/
│   └── 01-January/
├── Family/
│   ├── Birthdays/
│   └── Vacations/
└── Projects/
    └── HomeRenovation/

Creating Albums:

Albums are virtual collections that don’t affect file organization:

  1. Browse or search for photos
  2. Select photos (click checkbox on thumbnails)
  3. Click “Add to Album”
  4. Create new album or add to existing

Smart Albums:

PhotoPrism can create dynamic albums based on:

  • Date ranges
  • Locations
  • Tags and labels
  • Camera models
  • Quality scores

Duplicate Detection

PhotoPrism automatically detects duplicate and similar photos:

  1. Navigate to Photos
  2. Click Filter (funnel icon)
  3. Enable “Show Duplicates”
  4. Review and delete duplicates

PhotoPrism uses perceptual hashing to find:

  • Exact duplicates
  • Resized versions
  • Slightly edited copies
  • Similar compositions

AI and Machine Learning Features

Automatic Tagging and Classification

PhotoPrism uses TensorFlow to analyze every photo for:

Object Detection:

  • Common objects (car, dog, tree, building)
  • Specific breeds and models
  • Food and meals
  • Plants and flowers
  • Over 10,000 recognizable objects

Scene Recognition:

  • Indoor vs outdoor
  • Beach, mountain, city, forest
  • Day vs night
  • Weather conditions

Color Analysis:

  • Dominant colors
  • Color palettes
  • Black and white detection

Face Recognition Setup

Enable face recognition for automatic people tagging:

Step 1: Enable Face Detection

In Settings > General:

  • Enable “Detect Faces”
  • Set minimum face size (default: 50 pixels)
  • Set minimum face score (default: 9.0)

Step 2: Initial Face Scan

# Trigger face detection via CLI (optional, faster for large libraries)
docker compose exec photoprism photoprism faces index

# Or use web interface: Library > Index > Include Faces

Step 3: Name Recognized Faces

  1. Navigate to People
  2. Review detected face clusters
  3. Click on unnamed person
  4. Click “Edit” and add name
  5. Confirm or reject suggested matches

Step 4: Ongoing Recognition

PhotoPrism learns from your corrections:

  • Named faces help identify people in new photos
  • Rejection improves accuracy
  • Regular review improves recognition over time

Advanced Search Capabilities

PhotoPrism’s search supports complex queries:

Basic Searches:

dog                    # Find photos with dogs
beach sunset           # Photos with both beach and sunset
color:blue             # Photos with dominant blue color
camera:canon           # Photos taken with Canon cameras

Advanced Searches:

label:dog year:2023                    # Dogs in 2023
country:"United States" state:California  # California photos
f:2.8-                                 # Aperture f/2.8 or wider
mm:200+                                # Focal length 200mm or longer
people:"John Doe"                      # Photos of specific person
quality:3+                             # High quality photos only

Date Searches:

year:2023              # All of 2023
month:12               # December (any year)
day:25                 # 25th of any month
before:2023            # Before 2023
after:2023-06-15       # After specific date

Location Searches:

lat:37.7749            # Near specific coordinates
lng:-122.4194
geo:true               # Only geotagged photos
state:California       # Photos taken in California
city:"San Francisco"   # Specific city

Mobile App Configuration

PhotoPrism doesn’t have dedicated mobile apps, but supports standard protocols:

WebDAV Setup

PhotoPrism exposes your library via WebDAV, compatible with many mobile apps.

WebDAV URL:

http://YOUR-SERVER-IP:2342/originals/

Credentials:

  • Username: Your PhotoPrism username
  • Password: Your PhotoPrism password

iOS Photo Upload

Recommended App: PhotoSync

  1. Install PhotoSync from App Store
  2. Configure PhotoPrism target:
    • Protocol: WebDAV
    • Server: YOUR-SERVER-IP
    • Port: 2342
    • Path: /originals/
    • Username/Password: Your credentials
  3. Enable auto-upload:
    • Select albums to sync
    • Set trigger (WiFi only recommended)
    • Configure subfolder structure

Alternative: Documents by Readdle

  1. Install Documents app
  2. Add WebDAV connection
  3. Manually upload photos to import folder

Android Photo Upload

Recommended App: FolderSync

  1. Install FolderSync from Play Store
  2. Create new account:
    • Type: WebDAV
    • Server: YOUR-SERVER-IP:2342
    • Path: /originals/
    • Credentials: Your PhotoPrism login
  3. Create sync folder:
    • Local: DCIM/Camera
    • Remote: /import/mobile/
    • Direction: Upload only
  4. Schedule automatic sync

Alternative: Solid Explorer

  1. Install Solid Explorer
  2. Add WebDAV connection
  3. Set up automated file transfer

Progressive Web App (PWA)

PhotoPrism works as a PWA on mobile browsers:

  1. Open PhotoPrism in mobile browser
  2. Android: Menu > Add to Home Screen
  3. iOS: Share > Add to Home Screen

The PWA provides:

  • Offline viewing of cached photos
  • Photo upload capability
  • Full search and browse features
  • Responsive mobile interface

GPU Acceleration for ML Processing

GPU acceleration dramatically speeds up indexing and face recognition.

NVIDIA GPU Setup

Prerequisites:

  • NVIDIA GPU with compute capability 3.5 or higher
  • NVIDIA drivers installed on host
  • NVIDIA Container Toolkit installed

Install NVIDIA Container Toolkit:

# Add NVIDIA package repository
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey |   sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list |   sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' |   sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# Install toolkit
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Configure Docker
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Verify
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

Update Docker Compose:

services:
  photoprism:
    # ... existing configuration ...
    environment:
      PHOTOPRISM_TENSORFLOW_MODE: "gpu"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

Restart PhotoPrism:

docker compose down
docker compose up -d

Performance Gains:

  • Face detection: 5-10x faster
  • Object classification: 3-5x faster
  • Indexing: 2-4x overall speedup

Backup Strategies

Database Backup

Automated Daily Backup Script:

#!/bin/bash
# File: ~/photoprism/backup-db.sh

BACKUP_DIR=~/photoprism/backups
DATE=$(date +%Y%m%d_%H%M%S)
DB_PASSWORD="SecureDBPassword123"  # Match your compose file

mkdir -p $BACKUP_DIR

# Backup database
docker compose exec -T mariadb mysqldump   -u photoprism   -p$DB_PASSWORD   photoprism | gzip > $BACKUP_DIR/photoprism_db_$DATE.sql.gz

# Keep only last 30 days
find $BACKUP_DIR -name "photoprism_db_*.sql.gz" -mtime +30 -delete

echo "Database backup completed: photoprism_db_$DATE.sql.gz"

Make executable and schedule:

chmod +x ~/photoprism/backup-db.sh

# Add to crontab (daily at 2 AM)
crontab -e
# Add line:
0 2 * * * ~/photoprism/backup-db.sh >> ~/photoprism/backup.log 2>&1

Photo Library Backup

Option 1: Rsync to External Drive

#!/bin/bash
# File: ~/photoprism/backup-photos.sh

SOURCE=~/photoprism/storage/originals
DEST=/mnt/backup/photoprism/originals
DATE=$(date +%Y%m%d_%H%M%S)

# Sync to external drive
rsync -av --delete   --log-file=~/photoprism/backup-photos.log   $SOURCE/ $DEST/

echo "Photo backup completed at $DATE"

Option 2: Backup to Cloud Storage

Using rclone to backup to remote storage:

# Install rclone
curl https://rclone.org/install.sh | sudo bash

# Configure remote (interactive)
rclone config

# Backup script
#!/bin/bash
rclone sync ~/photoprism/storage/originals   remote:photoprism/originals   --progress   --exclude "*.tmp"

Option 3: Restic for Encrypted Backups

# Initialize repository
restic init --repo /mnt/backup/photoprism-restic

# Backup script
restic backup ~/photoprism/storage/originals   --repo /mnt/backup/photoprism-restic   --exclude "*.tmp"   --tag daily

# Verify backup
restic snapshots --repo /mnt/backup/photoprism-restic

Disaster Recovery Testing

Test your backups quarterly:

# 1. Stop PhotoPrism
docker compose down

# 2. Rename data directories
mv ~/photoprism/storage ~/photoprism/storage.old
mv ~/photoprism/database ~/photoprism/database.old

# 3. Restore from backup
mkdir -p ~/photoprism/storage/originals
mkdir -p ~/photoprism/database

# Restore photos
rsync -av /mnt/backup/photoprism/originals/   ~/photoprism/storage/originals/

# 4. Start PhotoPrism
docker compose up -d

# 5. Restore database
gunzip < backups/photoprism_db_LATEST.sql.gz |   docker compose exec -T mariadb mysql   -u photoprism   -pSecureDBPassword123   photoprism

# 6. Verify restoration
# Browse web interface, check random photos, verify albums

Troubleshooting

Indexing Stuck or Slow

Problem: Indexing takes forever or appears stuck.

Solutions:

  1. Check available resources:
docker stats photoprism
  1. Reduce concurrent workers:
environment:
  PHOTOPRISM_WORKERS: "1"  # Reduce from 2+
  1. Check for problematic files:
docker compose logs photoprism | grep -i error
  1. Restart indexing:
docker compose restart photoprism
# Web UI: Library > Index > Complete Rescan

High Memory Usage

Problem: PhotoPrism using excessive RAM.

Solutions:

  1. Reduce database buffer pool (docker-compose.yml):
command: >
  --innodb-buffer-pool-size=512M  # Reduce from 1G
  1. Limit thumbnail size:
environment:
  PHOTOPRISM_THUMB_SIZE: "1024"  # Reduce from 2048
  1. Add memory limits:
services:
  photoprism:
    mem_limit: 4g
    memswap_limit: 4g

Face Recognition Not Working

Problem: Faces not detected or named incorrectly.

Solutions:

  1. Verify face detection is enabled:
# Check settings
docker compose exec photoprism photoprism config

  1. Adjust face detection settings:

    • Settings > General
    • Lower minimum face score (try 7.0)
    • Lower minimum face size (try 40 pixels)

  2. Reset and re-scan faces:

docker compose exec photoprism photoprism faces reset -f
docker compose exec photoprism photoprism faces index

WebDAV Connection Issues

Problem: Cannot connect via WebDAV from mobile apps.

Solutions:

  1. Verify WebDAV is enabled:
environment:
  PHOTOPRISM_DISABLE_WEBDAV: "false"
  1. Test WebDAV URL:
curl -u admin:password http://YOUR-SERVER-IP:2342/originals/
  1. Check firewall:
sudo ufw allow 2342/tcp
  1. Use correct path:
    • URL: http://YOUR-SERVER-IP:2342/originals/
    • Note trailing slash is important

Performance Optimization

Slow web interface:

  1. Enable Redis caching:
services:
  photoprism:
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - "./cache/redis:/data"
  1. Optimize database:
docker compose exec mariadb mysqlcheck -u root -p --optimize photoprism
  1. Use reverse proxy caching (Nginx example):
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=photoprism_cache:10m;

location / {
    proxy_cache photoprism_cache;
    proxy_cache_valid 200 1h;
}

Conclusion

PhotoPrism brings professional-grade photo management to your homelab with powerful AI capabilities that rival commercial solutions. With automatic tagging, face recognition, and intelligent search, your photo library becomes instantly navigable without manual organization.

The combination of privacy, cost-effectiveness, and advanced features makes PhotoPrism an excellent choice for photographers, families, and privacy-conscious users who want complete control over their photo collections.

Next steps to enhance your PhotoPrism setup:

  • Configure reverse proxy with SSL for secure remote access
  • Set up automated backups to multiple locations
  • Integrate with external storage solutions for unlimited capacity
  • Explore the PhotoPrism+ membership for additional features
  • Join the PhotoPrism community for tips and updates

Your photos are memories worth protecting. PhotoPrism helps you preserve, organize, and enjoy them on your terms.