photoprism Installation Guide Installation Guide

photoprism is a free and open-source AI-powered photos app. PhotoPrism uses machine learning to organize your photo collection with face recognition and automatic tagging, serving as an alternative to Google Photos

Hardware Requirements:

CPU: 2+ cores recommended

RAM: 3GB minimum (8GB+ for AI features)

Storage: 2GB + photo storage

Network: HTTPS for web access

Operating System:

Linux: Any modern distribution (RHEL, Debian, Ubuntu, CentOS, Fedora, Arch, Alpine, openSUSE)

macOS: 10.14+ (Mojave or newer)

Windows: Windows Server 2016+ or Windows 10

FreeBSD: 11.0+

Network Requirements:

Port 2342 (default photoprism port)

None

Dependencies:

Docker (recommended) or Go 1.19+

MariaDB 10.5+ or SQLite

FFmpeg, Darktable, RawTherapee, ImageMagick

Exiftool, HeifConvert

System Access: root or sudo privileges required

This guide supports installation on:

RHEL 8/9 and derivatives (CentOS Stream, Rocky Linux, AlmaLinux)

Debian 11/12

Ubuntu 20.04/22.04/24.04 LTS

Arch Linux (rolling release)

Alpine Linux 3.18+

openSUSE Leap 15.5+ / Tumbleweed

SUSE Linux Enterprise Server (SLES) 15+

macOS 12+ (Monterey and later)

FreeBSD 13+

Windows 10/11/Server 2019+ (where applicable)

bash

# Install EPEL repository if needed
sudo dnf install -y epel-release

# Install photoprism
sudo dnf install -y photoprism

# Enable and start service
sudo systemctl enable --now photoprism

# Configure firewall
sudo firewall-cmd --permanent --add-port=2342/tcp
sudo firewall-cmd --reload

# Verify installation
photoprism version

bash

# Update package index
sudo apt update

# Install photoprism
sudo apt install -y photoprism

# Enable and start service
sudo systemctl enable --now photoprism

# Configure firewall
sudo ufw allow 2342

# Verify installation
photoprism version

bash

# Install photoprism
sudo pacman -S photoprism

# Enable and start service
sudo systemctl enable --now photoprism

# Verify installation
photoprism version

bash

# Install photoprism
apk add --no-cache photoprism

# Enable and start service
rc-update add photoprism default
rc-service photoprism start

# Verify installation
photoprism version

bash

# Install photoprism
sudo zypper install -y photoprism

# Enable and start service
sudo systemctl enable --now photoprism

# Configure firewall
sudo firewall-cmd --permanent --add-port=2342/tcp
sudo firewall-cmd --reload

# Verify installation
photoprism version

bash

# Using Homebrew
brew install photoprism

# Start service
brew services start photoprism

# Verify installation
photoprism version

bash

# Using pkg
pkg install photoprism

# Enable in rc.conf
echo 'photoprism_enable="YES"' >> /etc/rc.conf

# Start service
service photoprism start

# Verify installation
photoprism version

bash

# Using Chocolatey
choco install photoprism

# Or using Scoop
scoop install photoprism

# Verify installation
photoprism version

bash

# Create configuration directory
sudo mkdir -p /etc/photoprism

# Set up basic configuration
cat > /etc/photoprism/docker-compose.yml << 'EOF'
version: '3.5'

services:
  photoprism:
    image: photoprism/photoprism:latest
    environment:
      PHOTOPRISM_ADMIN_PASSWORD: "insecure"  # Change this!
      PHOTOPRISM_SITE_URL: "http://localhost:2342/"
      PHOTOPRISM_ORIGINALS_LIMIT: 5000  # MB
      PHOTOPRISM_HTTP_COMPRESSION: "gzip"
      PHOTOPRISM_DATABASE_DRIVER: "mysql"
      PHOTOPRISM_DATABASE_SERVER: "mariadb:3306"
      PHOTOPRISM_DATABASE_NAME: "photoprism"
      PHOTOPRISM_DATABASE_USER: "photoprism"
      PHOTOPRISM_DATABASE_PASSWORD: "insecure"
      PHOTOPRISM_DISABLE_CHOWN: "false"
      PHOTOPRISM_DISABLE_BACKUPS: "false"
      PHOTOPRISM_DETECT_NSFW: "false"
      PHOTOPRISM_UPLOAD_NSFW: "true"
EOF

# Test configuration
photoprism version

bash

# Enable service
sudo systemctl enable photoprism

# Start service
sudo systemctl start photoprism

# Stop service
sudo systemctl stop photoprism

# Restart service
sudo systemctl restart photoprism

# Check status
sudo systemctl status photoprism

# View logs
sudo journalctl -u photoprism -f

bash

# Enable service
rc-update add photoprism default

# Start service
rc-service photoprism start

# Stop service
rc-service photoprism stop

# Restart service
rc-service photoprism restart

# Check status
rc-service photoprism status

bash

# Enable in /etc/rc.conf
echo 'photoprism_enable="YES"' >> /etc/rc.conf

# Start service
service photoprism start

# Stop service
service photoprism stop

# Restart service
service photoprism restart

# Check status
service photoprism status

bash

# Using Homebrew services
brew services start photoprism
brew services stop photoprism
brew services restart photoprism

# Check status
brew services list | grep photoprism

powershell

# Start service
net start photoprism

# Stop service
net stop photoprism

# Using PowerShell
Start-Service photoprism
Stop-Service photoprism
Restart-Service photoprism

# Check status
Get-Service photoprism

yaml

environment:
  # Face recognition
  PHOTOPRISM_DISABLE_FACES: "false"
  PHOTOPRISM_FACE_SIZE: 50
  PHOTOPRISM_FACE_SCORE: 9.0
  PHOTOPRISM_FACE_OVERLAP: 42
  PHOTOPRISM_FACE_CLUSTER_SIZE: 80
  PHOTOPRISM_FACE_CLUSTER_SCORE: 15
  PHOTOPRISM_FACE_CLUSTER_CORE: 4
  PHOTOPRISM_FACE_CLUSTER_DIST: 0.64
  
  # Object detection
  PHOTOPRISM_DISABLE_CLASSIFICATION: "false"
  PHOTOPRISM_DISABLE_TENSORFLOW: "false"
  PHOTOPRISM_TENSORFLOW_VERSION: 2
  PHOTOPRISM_TENSORFLOW_MODEL_PATH: "/photoprism/assets/nasnet"
  
  # Image quality
  PHOTOPRISM_THUMB_FILTER: "lanczos"
  PHOTOPRISM_THUMB_UNCACHED: "false"
  PHOTOPRISM_THUMB_SIZE: 2048
  PHOTOPRISM_THUMB_SIZE_UNCACHED: 7680
  PHOTOPRISM_JPEG_SIZE: 7680
  PHOTOPRISM_JPEG_QUALITY: 92

yaml

volumes:
  # Original photos (read-only recommended)
  - "/mnt/photos:/photoprism/originals:ro"
  
  # Import folder (photos to be imported)
  - "/mnt/import:/photoprism/import"
  
  # Storage for sidecar files, thumbnails, database
  - "./storage:/photoprism/storage"
  
  # Optional: Additional media folders
  - "/mnt/videos:/photoprism/originals/videos:ro"
  - "/mnt/raw:/photoprism/originals/raw:ro"

environment:
  # Storage paths
  PHOTOPRISM_ORIGINALS_PATH: "/photoprism/originals"
  PHOTOPRISM_IMPORT_PATH: "/photoprism/import"
  PHOTOPRISM_STORAGE_PATH: "/photoprism/storage"
  PHOTOPRISM_BACKUP_PATH: "/photoprism/storage/backups"
  
  # File handling
  PHOTOPRISM_DISABLE_WEBDAV: "false"
  PHOTOPRISM_DISABLE_SETTINGS: "false"
  PHOTOPRISM_DISABLE_PLACES: "false"
  PHOTOPRISM_DISABLE_EXIFTOOL: "false"
  PHOTOPRISM_DISABLE_FFMPEG: "false"
  PHOTOPRISM_DISABLE_RAW: "false"

yaml

environment:
  # Workers and concurrency
  PHOTOPRISM_WORKERS: 4
  PHOTOPRISM_WAKEUP_INTERVAL: 900  # seconds
  PHOTOPRISM_AUTO_INDEX: 300  # seconds
  PHOTOPRISM_AUTO_IMPORT: -1  # disabled
  
  # Memory limits
  PHOTOPRISM_MEMORY_LIMIT: 4096  # MB
  PHOTOPRISM_ORIGINALS_LIMIT: 10000  # MB upload limit
  
  # Database connections
  PHOTOPRISM_DATABASE_CONNS: 10
  PHOTOPRISM_DATABASE_CONNS_IDLE: 5
  
  # HTTP server
  PHOTOPRISM_HTTP_HOST: "0.0.0.0"
  PHOTOPRISM_HTTP_PORT: 2342
  PHOTOPRISM_HTTP_COMPRESSION: "gzip"
  
  # Caching
  PHOTOPRISM_CACHE_ORIGINALS: "true"
  PHOTOPRISM_HTTP_CACHE_MAXAGE: 3600
  PHOTOPRISM_HTTP_CACHE_PUBLIC: "true"

yaml

environment:
  # Authentication
  PHOTOPRISM_AUTH_MODE: "password"  # or ldap
  PHOTOPRISM_ADMIN_PASSWORD: "strong-password-here"
  PHOTOPRISM_SESSION_MAXAGE: 86400
  PHOTOPRISM_SESSION_TIMEOUT: 14400
  
  # Restrictions
  PHOTOPRISM_DISABLE_SETTINGS: "true"  # For public instances
  PHOTOPRISM_DISABLE_RESTART: "true"
  PHOTOPRISM_DISABLE_BACKUPS: "false"
  PHOTOPRISM_READONLY: "false"  # Read-only mode
  
  # Downloads
  PHOTOPRISM_DOWNLOAD_ORIGINALS: "false"
  PHOTOPRISM_SHARE_ORIGINALS: "false"
  
  # Privacy
  PHOTOPRISM_DISABLE_SPONSORS: "true"
  PHOTOPRISM_DISABLE_PLACES: "true"  # No reverse geocoding
  PHOTOPRISM_PLACES_SOURCE: "none"  # or osm, places365

yaml

environment:
  PHOTOPRISM_AUTH_MODE: "ldap"
  PHOTOPRISM_LDAP_URI: "ldap://ldap.example.com:389"
  PHOTOPRISM_LDAP_BIND_DN: "cn=admin,dc=example,dc=com"
  PHOTOPRISM_LDAP_BIND_PASSWORD: "admin-password"
  PHOTOPRISM_LDAP_USER_SEARCH_BASE: "ou=users,dc=example,dc=com"
  PHOTOPRISM_LDAP_USER_SEARCH_FILTER: "(&(objectClass=person)(uid={username}))"
  PHOTOPRISM_LDAP_USER_ATTRIBUTES: "uid,cn,mail"
  PHOTOPRISM_LDAP_ADMIN_GROUP_DN: "cn=admins,ou=groups,dc=example,dc=com"

nginx

upstream photoprism_backend {
    server 127.0.0.1:2342;
}

server {
    listen 80;
    server_name photoprism.example.com;
    return 301 https://$server_name$request_uri;
}

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

    ssl_certificate /etc/ssl/certs/photoprism.example.com.crt;
    ssl_certificate_key /etc/ssl/private/photoprism.example.com.key;

    location / {
        proxy_pass http://photoprism_backend;
        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;
    }
}

apache

<VirtualHost *:80>
    ServerName photoprism.example.com
    Redirect permanent / https://photoprism.example.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName photoprism.example.com
    
    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/photoprism.example.com.crt
    SSLCertificateKeyFile /etc/ssl/private/photoprism.example.com.key
    
    ProxyRequests Off
    ProxyPreserveHost On
    
    ProxyPass / http://127.0.0.1:2342/
    ProxyPassReverse / http://127.0.0.1:2342/
</VirtualHost>

haproxy

frontend photoprism_frontend
    bind *:80
    bind *:443 ssl crt /etc/ssl/certs/photoprism.pem
    redirect scheme https if !{ ssl_fc }
    default_backend photoprism_backend

backend photoprism_backend
    balance roundrobin
    server photoprism1 127.0.0.1:2342 check

bash

# Set appropriate permissions
sudo chown -R photoprism:photoprism /etc/photoprism
sudo chmod 750 /etc/photoprism

# Configure firewall
sudo firewall-cmd --permanent --add-port=2342/tcp
sudo firewall-cmd --reload

# Enable SELinux policies (if applicable)
sudo setsebool -P httpd_can_network_connect on

sql

-- Create database
CREATE DATABASE photoprism CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- Create user
CREATE USER 'photoprism'@'%' IDENTIFIED BY 'secure-password';
GRANT ALL PRIVILEGES ON photoprism.* TO 'photoprism'@'%';
FLUSH PRIVILEGES;

-- Optimize for PhotoPrism
SET GLOBAL innodb_file_per_table = 1;
SET GLOBAL innodb_file_format = Barracuda;
SET GLOBAL innodb_large_prefix = 1;
SET GLOBAL innodb_default_row_format = DYNAMIC;

PostgreSQL Alternative

sql

-- Create database and user
CREATE DATABASE photoprism;
CREATE USER photoprism WITH ENCRYPTED PASSWORD 'secure-password';
GRANT ALL PRIVILEGES ON DATABASE photoprism TO photoprism;

-- Required extension
\c photoprism;
CREATE EXTENSION IF NOT EXISTS pg_trgm;

yaml

# PostgreSQL configuration
environment:
  PHOTOPRISM_DATABASE_DRIVER: "postgres"
  PHOTOPRISM_DATABASE_SERVER: "postgres:5432"
  PHOTOPRISM_DATABASE_NAME: "photoprism"
  PHOTOPRISM_DATABASE_USER: "photoprism"
  PHOTOPRISM_DATABASE_PASSWORD: "secure-password"

Database Maintenance

bash

#!/bin/bash
# Database optimization script

# Backup database
mysqldump -h mariadb -u photoprism -p photoprism | gzip > backup_$(date +%Y%m%d).sql.gz

# Optimize tables
mysql -h mariadb -u photoprism -p photoprism -e "OPTIMIZE TABLE files, photos, albums, labels;"

# Analyze tables
mysql -h mariadb -u photoprism -p photoprism -e "ANALYZE TABLE files, photos, albums, labels;"

bash

# Basic system tuning
echo 'net.core.somaxconn = 65535' | sudo tee -a /etc/sysctl.conf
echo 'net.ipv4.tcp_max_syn_backlog = 65535' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

bash

# Check service status
sudo systemctl status photoprism

# View logs
sudo journalctl -u photoprism -f

# Monitor resource usage
top -p $(pgrep photoprism)

bash

#!/bin/bash
# Basic backup script
BACKUP_DIR="/backup/photoprism"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"
tar -czf "$BACKUP_DIR/photoprism-backup-$DATE.tar.gz" /etc/photoprism /var/lib/photoprism

echo "Backup completed: $BACKUP_DIR/photoprism-backup-$DATE.tar.gz"

bash

# Stop service
sudo systemctl stop photoprism

# Restore from backup
tar -xzf /backup/photoprism/photoprism-backup-*.tar.gz -C /

# Start service
sudo systemctl start photoprism

1. Service won't start:

bash

# Check logs
sudo journalctl -u photoprism -n 100
sudo tail -f /var/log/photoprism/photoprism.log

# Check configuration
photoprism version

# Check permissions
ls -la /etc/photoprism

2. Connection issues:

bash

# Check if service is listening
sudo ss -tlnp | grep 2342

# Test connectivity
telnet localhost 2342

# Check firewall
sudo firewall-cmd --list-all

3. Performance issues:

bash

# Check resource usage
top -p $(pgrep photoprism)

# Check disk I/O
iotop -p $(pgrep photoprism)

# Check connections
ss -an | grep 2342

yaml

version: '3.8'
services:
  photoprism:
    image: photoprism:latest
    ports:
      - "2342:2342"
    volumes:
      - ./config:/etc/photoprism
      - ./data:/var/lib/photoprism
    restart: unless-stopped

Maintenance

bash

# RHEL/CentOS/Rocky/AlmaLinux
sudo dnf update photoprism

# Debian/Ubuntu
sudo apt update && sudo apt upgrade photoprism

# Arch Linux
sudo pacman -Syu photoprism

# Alpine Linux
apk update && apk upgrade photoprism

# openSUSE
sudo zypper update photoprism

# FreeBSD
pkg update && pkg upgrade photoprism

# Always backup before updates
tar -czf /backup/photoprism-pre-update-$(date +%Y%m%d).tar.gz /etc/photoprism

# Restart after updates
sudo systemctl restart photoprism

Regular Maintenance

bash

# Log rotation
sudo logrotate -f /etc/logrotate.d/photoprism

# Clean old logs
find /var/log/photoprism -name "*.log" -mtime +30 -delete

# Check disk usage
du -sh /var/lib/photoprism

Official Documentation: https://docs.photoprism.org/

GitHub Repository: https://github.com/photoprism/photoprism

Community Forum: https://forum.photoprism.org/

Best Practices Guide: https://docs.photoprism.org/best-practices

---

Note: This guide is part of the HowToMgr collection. Always refer to official documentation for the most up-to-date information.

1. Prerequisites

2. Supported Operating Systems

3. Installation

RHEL/CentOS/Rocky Linux/AlmaLinux

Debian/Ubuntu

Arch Linux

Alpine Linux

openSUSE/SLES

macOS

FreeBSD

Windows

Initial Configuration

Basic Configuration

5. Service Management

systemd (RHEL, Debian, Ubuntu, Arch, openSUSE)

OpenRC (Alpine Linux)

rc.d (FreeBSD)

launchd (macOS)

Windows Service Manager

Advanced Configuration

AI and Machine Learning Settings

Storage Configuration

Performance Optimization

Security Hardening

LDAP Authentication

Reverse Proxy Setup

nginx Configuration

Apache Configuration

HAProxy Configuration

Security Configuration

Basic Security Setup

Database Setup

MariaDB/MySQL Configuration

PostgreSQL Alternative

Database Maintenance

Performance Optimization

System Tuning

Monitoring

Basic Monitoring

9. Backup and Restore

Backup Script

Restore Procedure

6. Troubleshooting

Common Issues

Integration Examples

Docker Compose Example

Maintenance

Update Procedures

Regular Maintenance

Additional Resources

Related Miscellaneous Guides

ackee Installation Guide

Appwrite Installation Guide

arangodb Installation Guide