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
Environment
CLI Flag
Default
Description
PHOTOPRISM_AUTH_MODE
--auth-mode
password
authentication MODE (public, password)
PHOTOPRISM_ADMIN_USER
--admin-user
admin
admin login USERNAME
PHOTOPRISM_ADMIN_PASSWORD
--admin-password
initial admin PASSWORD, must have at least 8 characters
PHOTOPRISM_SESSION_MAXAGE
--session-maxage
1209600
time in SECONDS until API sessions expire automatically (-1 to disable)
PHOTOPRISM_SESSION_TIMEOUT
--session-timeout
604800
time in SECONDS until API sessions expire due to inactivity (-1 to disable)
Logging
Environment
CLI Flag
Default
Description
PHOTOPRISM_LOG_LEVEL
--log-level
info
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
Environment
CLI Flag
Default
Description
PHOTOPRISM_CONFIG_PATH
--config-path
config storage PATH, values in options.yml override CLI flags and environment variables if present
PHOTOPRISM_DEFAULTS_YAML
--defaults-yaml
/etc/photoprism/defaults.yml
load config defaults from FILE if exists, does not override CLI flags and environment variables
PHOTOPRISM_ORIGINALS_PATH
--originals-path
storage PATH of your original media files (photos and videos)
PHOTOPRISM_ORIGINALS_LIMIT
--originals-limit
1000
maximum size of media files in MB (1-100000; -1 to disable)
PHOTOPRISM_RESOLUTION_LIMIT
--resolution-limit
150
maximum resolution of media files in MEGAPIXELS (1-900; -1 to disable) sponsors only
PHOTOPRISM_STORAGE_PATH
--storage-path
writable storage PATH for sidecar, cache, and database files
PHOTOPRISM_SIDECAR_PATH
--sidecar-path
custom relative or absolute sidecar PATH optional
PHOTOPRISM_USERS_PATH
--users-path
custom users storage PATH optional
PHOTOPRISM_BACKUP_PATH
--backup-path
custom backup PATH for index backup files optional
PHOTOPRISM_CACHE_PATH
--cache-path
custom cache PATH for sessions and thumbnail files optional
PHOTOPRISM_IMPORT_PATH
--import-path
base PATH from which files can be imported to originals optional
PHOTOPRISM_IMPORT_DEST
--import-dest
relative originals PATH to which the files should be imported by default optional
PHOTOPRISM_ASSETS_PATH
--assets-path
assets PATH containing static resources like icons, models, and translations
PHOTOPRISM_TEMP_PATH
--temp-path
temporary file PATH optional
Index Workers
Environment
CLI Flag
Default
Description
PHOTOPRISM_WORKERS
--workers
4
maximum NUMBER of indexing workers, default depends on the number of physical cores
PHOTOPRISM_WAKEUP_INTERVAL
--wakeup-interval
15m0s
DURATION between worker runs required for face recognition and index maintenance (1-86400s)
PHOTOPRISM_AUTO_INDEX
--auto-index
300
WebDAV auto index safety delay in SECONDS (-1 to disable)
PHOTOPRISM_AUTO_IMPORT
--auto-import
180
WebDAV auto import safety delay in SECONDS (-1 to disable)
Feature Flags
Environment
CLI Flag
Default
Description
PHOTOPRISM_READONLY
--read-only
disable import, upload, delete, and all other operations that require write permissions
PHOTOPRISM_EXPERIMENTAL
--experimental
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 face detection and recognition (requires TensorFlow)
PHOTOPRISM_DISABLE_CLASSIFICATION
--disable-classification
disable image classification (requires TensorFlow)
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
automatically flag photos as private that MAY be offensive (requires TensorFlow)
PHOTOPRISM_UPLOAD_NSFW
--upload-nsfw
allow uploads that MAY be offensive (no effect without TensorFlow)
Customization
Environment
CLI Flag
Default
Description
PHOTOPRISM_DEFAULT_LOCALE
--default-locale
en
standard user interface language CODE
PHOTOPRISM_DEFAULT_THEME
--default-theme
standard user interface theme NAME sponsors only
PHOTOPRISM_APP_MODE
--app-mode
standalone
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_LEGAL_INFO
--legal-info
legal information TEXT, displayed in the page footer sponsors only
PHOTOPRISM_LEGAL_URL
--legal-url
legal information URL sponsors only
PHOTOPRISM_WALLPAPER_URI
--wallpaper-uri
login screen background image URI sponsors only
Environment
CLI Flag
Default
Description
PHOTOPRISM_CDN_URL
--cdn-url
content delivery network URL sponsors only
PHOTOPRISM_SITE_URL
--site-url
http://photoprism.me:2342/ 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
AI-Powered Photos App
site CAPTION
PHOTOPRISM_SITE_DESCRIPTION
--site-description
site DESCRIPTION optional
PHOTOPRISM_SITE_PREVIEW
--site-preview
sharing preview image URL sponsors only
Web Server
Environment
CLI Flag
Default
Description
PHOTOPRISM_TRUSTED_PROXY
--trusted-proxy
172.16.0.0/12
CIDR range from which reverse proxy headers can be trusted
PHOTOPRISM_PROXY_PROTO_HEADER
--proxy-proto-header
X-Forwarded-Proto
proxy protocol header NAME
PHOTOPRISM_PROXY_PROTO_HTTPS
--proxy-proto-https
https
forwarded HTTPS protocol NAME
PHOTOPRISM_HTTP_MODE
--http-mode
Web server MODE (debug, release, or test)
PHOTOPRISM_HTTP_COMPRESSION
--http-compression
Web server compression METHOD (none or gzip)
PHOTOPRISM_HTTP_HOST
--http-host
Web server IP address
PHOTOPRISM_HTTP_PORT
--http-port
2342
Web server port NUMBER
PHOTOPRISM_DISABLE_TLS
--disable-tls
disable HTTPS even if a certificate is available
Database Connection
Environment
CLI Flag
Default
Description
PHOTOPRISM_DATABASE_DRIVER
--database-driver
sqlite
database DRIVER (sqlite, mysql)
PHOTOPRISM_DATABASE_DSN
--database-dsn
database connection DSN (sqlite file, optional for mysql)
PHOTOPRISM_DATABASE_NAME
--database-name
photoprism
database schema NAME
PHOTOPRISM_DATABASE_SERVER
--database-server
database HOST incl. port e.g. "mariadb:3306" (or socket path)
PHOTOPRISM_DATABASE_USER
--database-user
photoprism
database user NAME
PHOTOPRISM_DATABASE_PASSWORD
--database-password
database user PASSWORD
PHOTOPRISM_DATABASE_CONNS
--database-conns
0
maximum NUMBER of open database connections
PHOTOPRISM_DATABASE_CONNS_IDLE
--database-conns-idle
0
maximum NUMBER of idle database connections
File Converters
Environment
CLI Flag
Default
Description
PHOTOPRISM_DARKTABLE_BIN
--darktable-bin
darktable-cli
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
RawTherapee CLI COMMAND for RAW to JPEG conversion
PHOTOPRISM_RAWTHERAPEE_BLACKLIST
--rawtherapee-blacklist
dng
do not use RawTherapee to convert files with these EXTENSIONS
PHOTOPRISM_SIPS_BIN
--sips-bin
sips
Sips COMMAND for RAW to JPEG conversion macOS only
PHOTOPRISM_SIPS_BLACKLIST
--sips-blacklist
avif,avifs
do not use Sips to convert files with these EXTENSIONS macOS only
PHOTOPRISM_HEIFCONVERT_BIN
--heifconvert-bin
heif-convert
HEIC/HEIF/AVIF image conversion COMMAND
PHOTOPRISM_FFMPEG_BIN
--ffmpeg-bin
ffmpeg
FFmpeg COMMAND for video transcoding and thumbnail extraction
PHOTOPRISM_FFMPEG_ENCODER
--ffmpeg-encoder
libx264
FFmpeg AVC encoder NAME sponsors only
PHOTOPRISM_FFMPEG_BITRATE
--ffmpeg-bitrate
50
maximum FFmpeg encoding BITRATE (Mbit/s)
PHOTOPRISM_EXIFTOOL_BIN
--exiftool-bin
exiftool
ExifTool COMMAND for extracting metadata
Security Tokens
Environment
CLI Flag
Default
Description
PHOTOPRISM_DOWNLOAD_TOKEN
--download-token
DEFAULT download URL token for originals (leave empty for a random value)
PHOTOPRISM_PREVIEW_TOKEN
--preview-token
DEFAULT thumbnail and video streaming URL token (leave empty for a random value)
Image Quality
Environment
CLI Flag
Default
Description
PHOTOPRISM_THUMB_COLOR
--thumb-color
sRGB
standard color PROFILE for thumbnails (leave blank to disable)
PHOTOPRISM_THUMB_FILTER
--thumb-filter
lanczos
image downscaling filter NAME (best to worst: blackman, lanczos, cubic, linear)
PHOTOPRISM_THUMB_SIZE
--thumb-size
2048
maximum size of thumbnails created during indexing in PIXELS (720-7680)
PHOTOPRISM_THUMB_SIZE_UNCACHED
--thumb-size-uncached
7680
maximum size of missing thumbnails created on demand in PIXELS (720-7680)
PHOTOPRISM_THUMB_UNCACHED
--thumb-uncached
enable on-demand creation of missing thumbnails (high memory and cpu usage)
PHOTOPRISM_JPEG_QUALITY
--jpeg-quality
85
a higher value increases the QUALITY and file size of JPEG images and thumbnails (25-100)
PHOTOPRISM_JPEG_SIZE
--jpeg-size
7680
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:
Environment
CLI Flag
Default
Description
PHOTOPRISM_FACE_SIZE
--face-size
50
minimum size of faces in PIXELS (20-10000)
PHOTOPRISM_FACE_SCORE
--face-score
9.000000
minimum face QUALITY score (1-100)
PHOTOPRISM_FACE_OVERLAP
--face-overlap
42
face area overlap threshold in PERCENT (1-100)
PHOTOPRISM_FACE_CLUSTER_SIZE
--face-cluster-size
80
minimum size of automatically clustered faces in PIXELS (20-10000) sponsors only
PHOTOPRISM_FACE_CLUSTER_SCORE
--face-cluster-score
15
minimum QUALITY score of automatically clustered faces (1-100) sponsors only
PHOTOPRISM_FACE_CLUSTER_CORE
--face-cluster-core
4
NUMBER of faces forming a cluster core (1-100) sponsors only
PHOTOPRISM_FACE_CLUSTER_DIST
--face-cluster-dist
0.640000
similarity DISTANCE of faces forming a cluster core (0.1-1.5) sponsors only
PHOTOPRISM_FACE_MATCH_DIST
--face-match-dist
0.460000
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:
Environment
CLI Flag
Default
Description
PHOTOPRISM_PID_FILENAME
--pid-filename
process id FILE daemon-mode only
PHOTOPRISM_LOG_FILENAME
--log-filename
server log FILE daemon-mode only
Docker Image
The following variables are used by our Docker images only and have no effect otherwise:
Environment
Default
Description
PHOTOPRISM_UID
0
run as a non-root user after initialization (supported: 0, 33, 50-99, 500-600, and 900-1200)
PHOTOPRISM_GID
0
run with a specific group id after initialization, to be used together with PHOTOPRISM_UID
PHOTOPRISM_UMASK
0002
file-creation mode (default: u=rwx,g=rwx,o=rx)
PHOTOPRISM_INIT
run/install on first startup (options: update https gpu tensorflow davfs clitools clean)
PHOTOPRISM_DISABLE_CHOWN
false
disable updating storage permissions via chmod and chown on startup