Config Options
Changing values in docker-compose.yml
or in Advanced Settings
always requires a restart to take effect. Open a terminal, run docker-compose stop
and then
docker-compose up -d
to restart all services.
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
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