Authentication
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_ADMIN_PASSWORD | admin-password, pw | initial admin PASSWORD, must have at least 8 characters |
| PHOTOPRISM_PUBLIC | public, p | disable password authentication, WebDAV, and the advanced settings page |
| PHOTOPRISM_AUTH | auth, a | always require password authentication, overrides the public flag if it is set |
Logging
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_LOG_LEVEL | log-level, l | log message verbosity LEVEL (trace, debug, info, warning, error, fatal, panic) |
| PHOTOPRISM_DEBUG | debug | enable debug mode, show non-essential log messages |
| PHOTOPRISM_TRACE | trace | enable trace mode, show all log messages |
Storage
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_CONFIG_PATH | config-path, c | config storage PATH, values in options.yml override CLI flags and environment variables if present |
| PHOTOPRISM_DEFAULTS_YAML | defaults-yaml, y | load config defaults from FILE if exists, does not override CLI flags and environment variables |
| PHOTOPRISM_ORIGINALS_PATH | originals-path, o | storage PATH of your original media files (photos and videos) |
| PHOTOPRISM_ORIGINALS_LIMIT | originals-limit, mb | maximum size of media files in MB (1-100000; -1 to disable) |
| PHOTOPRISM_RESOLUTION_LIMIT | resolution-limit, mp | maximum resolution of media files in MEGAPIXELS (1-900; -1 to disable) sponsors only |
| PHOTOPRISM_STORAGE_PATH | storage-path, s | writable storage PATH for sidecar, cache, and database files |
| PHOTOPRISM_SIDECAR_PATH | sidecar-path, sc | custom relative or absolute sidecar PATH optional |
| PHOTOPRISM_BACKUP_PATH | backup-path, ba | custom backup PATH for index backup files optional |
| PHOTOPRISM_CACHE_PATH | cache-path, ca | custom cache PATH for sessions and thumbnail files optional |
| PHOTOPRISM_IMPORT_PATH | import-path, im | base PATH from which files can be imported to originals optional |
| PHOTOPRISM_ASSETS_PATH | assets-path, as | assets PATH containing static resources like icons, models, and translations |
| PHOTOPRISM_TEMP_PATH | temp-path, tmp | temporary file PATH optional |
Index Workers
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_WORKERS | workers, w | maximum NUMBER of indexing workers, default depends on the number of physical cores |
| PHOTOPRISM_WAKEUP_INTERVAL | wakeup-interval, i | DURATION between worker runs required for face recognition and index maintenance (1-86400s) |
| PHOTOPRISM_AUTO_INDEX | auto-index | WebDAV auto index safety delay in SECONDS (-1 to disable) |
| PHOTOPRISM_AUTO_IMPORT | auto-import | WebDAV auto import safety delay in SECONDS (-1 to disable) |
Feature Flags
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_READONLY | read-only, r | disable import, upload, delete, and all other operations that require write permissions |
| PHOTOPRISM_EXPERIMENTAL | experimental, e | enable experimental features |
| PHOTOPRISM_DISABLE_WEBDAV | disable-webdav | disable built-in WebDAV server |
| PHOTOPRISM_DISABLE_SETTINGS | disable-settings | disable settings UI and API |
| PHOTOPRISM_DISABLE_PLACES | disable-places | disable reverse geocoding and maps |
| PHOTOPRISM_DISABLE_BACKUPS | disable-backups | disable backing up albums and photo metadata to YAML files |
| PHOTOPRISM_DISABLE_TENSORFLOW | disable-tensorflow | disable all features depending on TensorFlow |
| PHOTOPRISM_DISABLE_FACES | disable-faces | disable facial recognition |
| PHOTOPRISM_DISABLE_CLASSIFICATION | disable-classification | disable image classification |
| PHOTOPRISM_DISABLE_FFMPEG | disable-ffmpeg | disable video transcoding and thumbnail extraction with FFmpeg |
| PHOTOPRISM_DISABLE_EXIFTOOL | disable-exiftool | disable creating JSON metadata sidecar files with ExifTool |
| PHOTOPRISM_DISABLE_HEIFCONVERT | disable-heifconvert | disable conversion of HEIC/HEIF files |
| PHOTOPRISM_DISABLE_DARKTABLE | disable-darktable | disable conversion of RAW files with Darktable |
| PHOTOPRISM_DISABLE_RAWTHERAPEE | disable-rawtherapee | disable conversion of RAW files with RawTherapee |
| PHOTOPRISM_DISABLE_SIPS | disable-sips | disable conversion of RAW files with Sips macOS only |
| PHOTOPRISM_DISABLE_RAW | disable-raw | disable indexing and conversion of RAW files |
| PHOTOPRISM_RAW_PRESETS | raw-presets | enables applying user presets when converting RAW files (reduces performance) |
| PHOTOPRISM_EXIF_BRUTEFORCE | exif-bruteforce | always perform a brute-force search if no Exif headers were found |
| PHOTOPRISM_DETECT_NSFW | detect-nsfw | flag photos as private that may be offensive (requires TensorFlow) |
| PHOTOPRISM_UPLOAD_NSFW | upload-nsfw, n | allow uploads that may be offensive |
Customization
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_DEFAULT_LOCALE | default-locale, lang | standard user interface language CODE |
| PHOTOPRISM_DEFAULT_THEME | default-theme | standard user interface theme NAME sponsors only |
| PHOTOPRISM_APP_MODE | app-mode | progressive web app MODE (fullscreen, standalone, minimal-ui, browser) |
| PHOTOPRISM_APP_ICON | app-icon | progressive web app ICON (logo, app, crisp, mint, bold) sponsors only |
| PHOTOPRISM_APP_NAME | app-name | progressive web app NAME when installed on a device sponsors only |
| PHOTOPRISM_IMPRINT | imprint | legal INFORMATION, displayed in the page footer sponsors only |
| PHOTOPRISM_IMPRINT_URL | imprint-url | legal information URL sponsors only |
| PHOTOPRISM_WALLPAPER_URI | wallpaper-uri | login screen background image URI sponsors only |
Site Information
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_CDN_URL | cdn-url | content delivery network URL sponsors only |
| PHOTOPRISM_SITE_URL | site-url, url | public site URL |
| PHOTOPRISM_SITE_AUTHOR | site-author | site OWNER, copyright, or artist |
| PHOTOPRISM_SITE_TITLE | site-title | site TITLE sponsors only |
| PHOTOPRISM_SITE_CAPTION | site-caption | site CAPTION |
| PHOTOPRISM_SITE_DESCRIPTION | site-description | site DESCRIPTION optional |
| PHOTOPRISM_SITE_PREVIEW | site-preview | sharing preview image URL sponsors only |
Web Server
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_HTTP_PORT | http-port, port | http server port NUMBER |
| PHOTOPRISM_HTTP_HOST | http-host, ip | http server IP address |
| PHOTOPRISM_HTTP_MODE | http-mode, mode | http server MODE (debug, release, or test) |
| PHOTOPRISM_HTTP_COMPRESSION | http-compression, z | http server compression METHOD (none or gzip) |
Database Connection
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_DATABASE_DRIVER | database-driver, db | database DRIVER (sqlite, mysql) |
| PHOTOPRISM_DATABASE_DSN | database-dsn, dsn | database connection DSN (sqlite file, optional for mysql) |
| PHOTOPRISM_DATABASE_SERVER | database-server, db-server | database HOST incl. port e.g. "mariadb:3306" (or socket path) |
| PHOTOPRISM_DATABASE_NAME | database-name, db-name | database schema NAME |
| PHOTOPRISM_DATABASE_USER | database-user, db-user | database user NAME |
| PHOTOPRISM_DATABASE_PASSWORD | database-password, db-pass | database user PASSWORD |
| PHOTOPRISM_DATABASE_CONNS | database-conns | maximum NUMBER of open database connections |
| PHOTOPRISM_DATABASE_CONNS_IDLE | database-conns-idle | maximum NUMBER of idle database connections |
File Converters
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_DARKTABLE_BIN | darktable-bin | Darktable CLI COMMAND for RAW to JPEG conversion |
| PHOTOPRISM_DARKTABLE_BLACKLIST | darktable-blacklist | do not use Darktable to convert files with these EXTENSIONS |
| PHOTOPRISM_DARKTABLE_CACHE_PATH | darktable-cache-path | custom Darktable cache PATH |
| PHOTOPRISM_DARKTABLE_CONFIG_PATH | darktable-config-path | custom Darktable config PATH |
| PHOTOPRISM_RAWTHERAPEE_BIN | rawtherapee-bin | RawTherapee CLI COMMAND for RAW to JPEG conversion |
| PHOTOPRISM_RAWTHERAPEE_BLACKLIST | rawtherapee-blacklist | do not use RawTherapee to convert files with these EXTENSIONS |
| PHOTOPRISM_SIPS_BIN | sips-bin | Sips COMMAND for RAW to JPEG conversion macOS only |
| PHOTOPRISM_HEIFCONVERT_BIN | heifconvert-bin | HEIC/HEIF image conversion COMMAND |
| PHOTOPRISM_FFMPEG_BIN | ffmpeg-bin | FFmpeg COMMAND for video transcoding and thumbnail extraction |
| PHOTOPRISM_FFMPEG_ENCODER | ffmpeg-encoder, vc | FFmpeg AVC encoder NAME sponsors only |
| PHOTOPRISM_FFMPEG_BITRATE | ffmpeg-bitrate, vb | maximum FFmpeg encoding BITRATE (Mbit/s) |
| PHOTOPRISM_EXIFTOOL_BIN | exiftool-bin | ExifTool COMMAND for extracting metadata |
Security Tokens
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_DOWNLOAD_TOKEN | download-token | SECRET download URL token for originals (default: random) |
| PHOTOPRISM_PREVIEW_TOKEN | preview-token | SECRET thumbnail and video streaming URL token (default: random) |
Image Quality
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_THUMB_COLOR | thumb-color | standard color PROFILE for thumbnails (leave blank to disable) |
| PHOTOPRISM_THUMB_FILTER | thumb-filter, filter | image downscaling filter NAME (best to worst: blackman, lanczos, cubic, linear) |
| PHOTOPRISM_THUMB_SIZE | thumb-size | maximum size of thumbnails created during indexing in PIXELS (720-7680) |
| PHOTOPRISM_THUMB_SIZE_UNCACHED | thumb-size-uncached | maximum size of missing thumbnails created on demand in PIXELS (720-7680) |
| PHOTOPRISM_THUMB_UNCACHED | thumb-uncached, u | enable on-demand creation of missing thumbnails (high memory and cpu usage) |
| PHOTOPRISM_JPEG_QUALITY | jpeg-quality, q | QUALITY of created JPEG sidecars and thumbnails (25-100, best, high, default, low, worst) |
| PHOTOPRISM_JPEG_SIZE | jpeg-size | maximum size of created JPEG sidecar files in PIXELS (720-30000) |
Face Recognition
To recognize faces, PhotoPrism first extracts crops from your images using a library based on pixel intensity comparisons. These are then fed into TensorFlow to compute 512-dimensional vectors for characterization. In the final step, the DBSCAN algorithm attempts to cluster these so-called face embeddings, so they can be matched to persons with just a few clicks. A reasonable range for the similarity distance between face embeddings is between 0.60 and 0.70, with a higher value being more aggressive and leading to larger clusters with more false positives. To cluster a smaller number of faces, you can reduce the core to 3 or 2 similar faces.
We recommend that only advanced users change these parameters:
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_FACE_SIZE | face-size | minimum size of faces in PIXELS (20-10000) |
| PHOTOPRISM_FACE_SCORE | face-score | minimum face QUALITY score (1-100) |
| PHOTOPRISM_FACE_OVERLAP | face-overlap | face area overlap threshold in PERCENT (1-100) |
| PHOTOPRISM_FACE_CLUSTER_SIZE | face-cluster-size | minimum size of automatically clustered faces in PIXELS (20-10000) sponsors only |
| PHOTOPRISM_FACE_CLUSTER_SCORE | face-cluster-score | minimum QUALITY score of automatically clustered faces (1-100) sponsors only |
| PHOTOPRISM_FACE_CLUSTER_CORE | face-cluster-core | NUMBER of faces forming a cluster core (1-100) sponsors only |
| PHOTOPRISM_FACE_CLUSTER_DIST | face-cluster-dist | similarity DISTANCE of faces forming a cluster core (0.1-1.5) sponsors only |
| PHOTOPRISM_FACE_MATCH_DIST | face-match-dist | similarity OFFSET for matching faces with existing clusters (0.1-1.5) sponsors only |
Daemon Mode
If you start the server as a daemon in the background, you can additionally specify a filename for the log and the process ID:
| Variable | Flag | Usage |
|---|---|---|
| PHOTOPRISM_PID_FILENAME | pid-filename | process id FILE daemon-mode only |
| PHOTOPRISM_LOG_FILENAME | log-filename | server log FILE daemon-mode only |