Authentication

Environment CLI Flag Default Description
PHOTOPRISM_AUTH_MODE –auth-mode password authentication MODE (public, password)
PHOTOPRISM_ADMIN_USER, PHOTOPRISM_ADMIN_USERNAME –admin-user admin USERNAME of the superadmin account that is created on first startup
PHOTOPRISM_ADMIN_PASSWORD –admin-password initial PASSWORD of the superadmin account (8-72 characters)
PHOTOPRISM_ADMIN_SCOPE –admin-scope * admin authorization SCOPE as space-separated resources, or ‘*’ for full access pro
PHOTOPRISM_PASSWORD_LENGTH –password-length 8 minimum password LENGTH in characters
PHOTOPRISM_PASSWORD_RESET_URI –password-reset-uri custom password reset page URI pro
PHOTOPRISM_REGISTER_URI –register-uri custom registration page URI pro
PHOTOPRISM_LOGIN_URI –login-uri custom login page URI pro
PHOTOPRISM_LOGIN_INFO –login-info custom login footer info TEXT pro
PHOTOPRISM_OIDC_URI –oidc-uri issuer URI for single sign-on via OpenID Connect, e.g. https://accounts.google.com
PHOTOPRISM_OIDC_CLIENT –oidc-client client ID for single sign-on via OpenID Connect
PHOTOPRISM_OIDC_SECRET –oidc-secret client SECRET for single sign-on via OpenID Connect
PHOTOPRISM_OIDC_SCOPES –oidc-scopes openid email profile address client authorization SCOPES for single sign-on via OpenID Connect
PHOTOPRISM_OIDC_PROVIDER –oidc-provider custom identity provider NAME, e.g. Google
PHOTOPRISM_OIDC_ICON –oidc-icon custom identity provider icon URI
PHOTOPRISM_OIDC_REDIRECT –oidc-redirect false automatically redirects unauthenticated users to the configured identity provider
PHOTOPRISM_OIDC_REGISTER –oidc-register false allows new users to create an account when they sign in with OpenID Connect
PHOTOPRISM_OIDC_USERNAME –oidc-username preferred_username preferred username CLAIM for new OpenID Connect users (preferred_username, name, nickname, email)
PHOTOPRISM_OIDC_DOMAIN –oidc-domain verified email domain NAME for single sign-on via OpenID Connect pro
PHOTOPRISM_OIDC_ROLE –oidc-role guest default user ROLE for new OpenID Connect users pro
PHOTOPRISM_OIDC_GROUP_CLAIM –oidc-group-claim group claim NAME to read from OIDC tokens (default groups)
PHOTOPRISM_OIDC_GROUP –oidc-group require membership in at least one group ID (repeat flag to add multiple)
PHOTOPRISM_OIDC_GROUP_ROLE –oidc-group-role map GROUP=ROLE; repeat to add more (roles: admin, or guest)
PHOTOPRISM_OIDC_WEBDAV –oidc-webdav false allows new OpenID Connect users to use WebDAV when they have a role that allows it
PHOTOPRISM_DISABLE_OIDC –disable-oidc false disables single sign-on via OpenID Connect, even if an identity provider has been configured
PHOTOPRISM_LDAP_URI –ldap-uri LDAP directory URI, e.g. ldaps://example.com:636 for LDAP over SSL/TLS pro
PHOTOPRISM_LDAP_CERT –ldap-cert LDAP directory SSL/TLS certificate FILENAME (.pem) pro
PHOTOPRISM_LDAP_INSECURE –ldap-insecure false skips SSL/TLS certificate verification when using LDAPS pro
PHOTOPRISM_LDAP_CHASE –ldap-chase false automatically chases referrals when there are multiple LDAP servers pro
PHOTOPRISM_LDAP_CHASE_INSECURE –ldap-chase-insecure false skips SSL/TLS certificate verification when chasing referrals pro
PHOTOPRISM_LDAP_SYNC –ldap-sync false updates name, email, role, and attributes from LDAP directory on login pro
PHOTOPRISM_LDAP_BIND –ldap-bind simple LDAP authentication TYPE (simple, md5) pro
PHOTOPRISM_LDAP_BIND_DN –ldap-bind-dn userprincipalname LDAP username attribute DN, e.g. cn or userprincipalname pro
PHOTOPRISM_LDAP_BASE_DN –ldap-base-dn LDAP directory base DN, e.g. dc=example,dc=com pro
PHOTOPRISM_LDAP_ROLE –ldap-role LDAP default ROLE (admin, manager, user, viewer, contributor, guest), leave blank for none pro
PHOTOPRISM_LDAP_ROLE_DN –ldap-role-dn custom LDAP group or attribute DN for specifying the role pro
PHOTOPRISM_LDAP_NOLOGIN –ldap-nologin false disables web login for new LDAP users by default pro
PHOTOPRISM_LDAP_NOLOGIN_DN –ldap-nologin-dn custom LDAP attribute DN to disable web login pro
PHOTOPRISM_LDAP_WEBDAV –ldap-webdav false allows new LDAP users to use WebDAV when they have a role that allows it pro
PHOTOPRISM_LDAP_WEBDAV_DN –ldap-webdav-dn custom LDAP attribute DN to enable WebDAV access pro
PHOTOPRISM_LDAP_BASE_PATH_DN –ldap-base-path-dn user base path LDAP attribute DN pro
PHOTOPRISM_LDAP_UPLOAD_PATH_DN –ldap-upload-path-dn user upload path LDAP attribute DN pro
PHOTOPRISM_DISABLE_LDAP –disable-ldap false disables authentication via LDAP pro
PHOTOPRISM_SESSION_MAXAGE –session-maxage 1209600 session expiration time in SECONDS, doubled for accounts with 2FA (-1 to disable)
PHOTOPRISM_SESSION_TIMEOUT –session-timeout 604800 session idle time in SECONDS, doubled for accounts with 2FA (-1 to disable)
PHOTOPRISM_SESSION_CACHE –session-cache 900 session cache duration in SECONDS (60-3600)

Logging

Environment CLI Flag Default Description
PHOTOPRISM_LOG_LEVEL –log-level info log message verbosity LEVEL (trace, debug, info, warning, error)
PHOTOPRISM_AUDIT_LEVEL –audit-level warning audit log recording LEVEL (debug, info, warning, error) pro
PHOTOPRISM_PROD –prod false disables debug mode and only logs startup warnings and errors
PHOTOPRISM_DEBUG –debug false enables debug mode for development and troubleshooting
PHOTOPRISM_TRACE –trace false enables trace mode to display all debug and trace logs

Storage

Environment CLI Flag Default Description
PHOTOPRISM_STORAGE_PATH –storage-path writable storage PATH for sidecar, cache, and database files
PHOTOPRISM_STORAGE_FREE –storage-free -1 minimum PERCENT (1-99) of free storage required for indexing, importing, and uploads, -1 disables the check
PHOTOPRISM_CONFIG_PATH –config-path config storage PATH or options.yml filename, values in this file override CLI flags and environment variables if present
PHOTOPRISM_DEFAULTS_YAML –defaults-yaml /etc/photoprism/defaults.yml loads default config values from FILENAME if it exists, does not override CLI flags or 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)
PHOTOPRISM_USERS_PATH –users-path users relative PATH to create base and upload subdirectories for users
PHOTOPRISM_IMPORT_PATH –import-path base PATH from which files can be imported to originals optional
PHOTOPRISM_IMPORT_DEST –import-dest relative originals PATH in which files should be imported by default optional
PHOTOPRISM_IMPORT_ALLOW –import-allow restricts imports to these file types (comma-separated list of EXTENSIONS; leave blank to allow all)
PHOTOPRISM_UPLOAD_NSFW –upload-nsfw false allows uploads that might be offensive (when disabled, files flagged by the NSFW model are rejected before indexing)
PHOTOPRISM_UPLOAD_ALLOW –upload-allow restricts uploads to these file types (comma-separated list of EXTENSIONS; leave blank to allow all)
PHOTOPRISM_UPLOAD_ARCHIVES –upload-archives false allows upload of zip archives (will be extracted before import)
PHOTOPRISM_UPLOAD_LIMIT –upload-limit 1000 maximum total size of uploaded files in MB (1-100000; -1 to disable)
PHOTOPRISM_CACHE_PATH –cache-path custom cache PATH for sessions and thumbnail files optional
PHOTOPRISM_TEMP_PATH –temp-path temporary file PATH optional
PHOTOPRISM_ASSETS_PATH –assets-path assets PATH containing static resources like icons, models, and translations
PHOTOPRISM_CUSTOM_ASSETS_PATH –custom-assets-path assets PATH for custom templates and wallpapers pro
PHOTOPRISM_MODELS_PATH –models-path custom model assets PATH where computer vision models are located

Sidecar Files

Environment CLI Flag Default Description
PHOTOPRISM_SIDECAR_PATH –sidecar-path custom relative or absolute sidecar PATH optional
PHOTOPRISM_SIDECAR_YAML –sidecar-yaml true creates YAML sidecar files to back up picture metadata

Usage

Environment CLI Flag Default Description
PHOTOPRISM_USAGE_INFO –usage-info false displays storage usage information in the user interface
PHOTOPRISM_FILES_QUOTA –files-quota 0 maximum total size of all indexed files in GB (0 for unlimited)
PHOTOPRISM_USERS_QUOTA –users-quota 0 maximum NUMBER of active user accounts, excluding guests (0 for unlimited) pro

Backup

Environment CLI Flag Default Description
PHOTOPRISM_BACKUP_PATH –backup-path custom base PATH for creating and restoring backups optional
PHOTOPRISM_BACKUP_SCHEDULE –backup-schedule daily backup SCHEDULE in cron format (e.g. “0 12 * * *” for daily at noon) or at a random time (daily, weekly)
PHOTOPRISM_BACKUP_RETAIN –backup-retain 3 NUMBER of index backups to keep (-1 to keep all)
PHOTOPRISM_BACKUP_DATABASE –backup-database true enables regular backups based on the configured schedule
PHOTOPRISM_BACKUP_ALBUMS –backup-albums true enables the use of YAML files for backing up album metadata

Indexing

Environment CLI Flag Default Description
PHOTOPRISM_INDEX_WORKERS, PHOTOPRISM_WORKERS –index-workers auto maximum NUMBER of indexing workers, or ‘auto’ to derive from the available CPU cores
PHOTOPRISM_INDEX_SCHEDULE –index-schedule indexing SCHEDULE in cron format (e.g. “@every 3h” for every 3 hours; "" to disable)
PHOTOPRISM_WAKEUP_INTERVAL –wakeup-interval 15m0s TIME between facial recognition, file sync, and metadata worker runs (1-86400s)
PHOTOPRISM_AUTO_INDEX –auto-index 300 delay before automatically indexing files in SECONDS when uploading via WebDAV (-1 to disable)
PHOTOPRISM_AUTO_IMPORT –auto-import -1 delay before automatically importing files in SECONDS when uploading via WebDAV (-1 to disable)

Feature Flags

Environment CLI Flag Default Description
PHOTOPRISM_READONLY –read-only false disables features that require write permission for the originals folder
PHOTOPRISM_EXPERIMENTAL –experimental false enables new features that may be incomplete or unstable
PHOTOPRISM_DISABLE_FRONTEND –disable-frontend false disables the web user interface so that only the service API endpoints are accessible
PHOTOPRISM_DISABLE_SETTINGS –disable-settings false disables the settings frontend and related API endpoints, e.g. in combination with public mode
PHOTOPRISM_DISABLE_BACKUPS –disable-backups false prevents database and album backups as well as YAML sidecar files from being created
PHOTOPRISM_DISABLE_RESTART –disable-restart false prevents admins from restarting the server through the user interface
PHOTOPRISM_DISABLE_WEBDAV –disable-webdav false prevents other apps from accessing PhotoPrism as a shared network drive
PHOTOPRISM_DISABLE_MCP –disable-mcp false disables the Model Context Protocol (MCP) API endpoint for AI agent integrations
PHOTOPRISM_DISABLE_PLACES –disable-places false disables interactive world maps and reverse geocoding
PHOTOPRISM_DISABLE_TENSORFLOW –disable-tensorflow false disables face recognition with TensorFlow deprecated
PHOTOPRISM_DISABLE_FACES –disable-faces false disables face detection and recognition (requires TensorFlow)
PHOTOPRISM_DISABLE_CLASSIFICATION –disable-classification false disables all image classification and label generation
PHOTOPRISM_DISABLE_FFMPEG –disable-ffmpeg false disables video transcoding and thumbnail extraction with FFmpeg
PHOTOPRISM_DISABLE_EXIFTOOL –disable-exiftool false disables metadata extraction with ExifTool (required for full Video, Live Photo, and XMP support)
PHOTOPRISM_DISABLE_SIPS –disable-sips false disables file conversion using the sips command under macOS
PHOTOPRISM_DISABLE_DARKTABLE –disable-darktable false disables conversion of RAW images with Darktable
PHOTOPRISM_DISABLE_RAWTHERAPEE –disable-rawtherapee false disables conversion of RAW images with RawTherapee
PHOTOPRISM_DISABLE_IMAGEMAGICK –disable-imagemagick false disables conversion of image files with ImageMagick
PHOTOPRISM_DISABLE_HEIFCONVERT –disable-heifconvert false disables conversion of HEIC images with libheif
PHOTOPRISM_DISABLE_RSVGCONVERT –disable-rsvgconvert false disables conversion of SVG graphics with librsvg pro
PHOTOPRISM_DISABLE_VECTORS –disable-vectors false disables vector graphics support pro
PHOTOPRISM_DISABLE_JPEGXL –disable-jpegxl false disables JPEG XL file format support
PHOTOPRISM_DISABLE_RAW –disable-raw false disables indexing and conversion of RAW images
PHOTOPRISM_RAW_PRESETS –raw-presets false enables custom user presets when converting RAW images (reduces performance)
PHOTOPRISM_EXIF_BRUTEFORCE –exif-bruteforce false performs a brute-force search if no Exif headers were found

Customization

Environment CLI Flag Default Description
PHOTOPRISM_DEFAULT_LOCALE –default-locale en default user interface language CODE
PHOTOPRISM_DEFAULT_TIMEZONE –default-timezone Local default time zone NAME, e.g. for scheduling backups
PHOTOPRISM_DEFAULT_THEME –default-theme default user interface theme NAME
PHOTOPRISM_THEME_URL –theme-url download URL for installing a custom theme if none is installed portal
PHOTOPRISM_PLACES_LOCALE –places-locale local location details language CODE, e.g. en, de, or local
PHOTOPRISM_APP_NAME –app-name app NAME when installed as a Progressive Web App (PWA)
PHOTOPRISM_APP_MODE –app-mode standalone app display MODE (fullscreen, standalone, minimal-ui, browser)
PHOTOPRISM_APP_ICON –app-icon home screen app ICON (logo, app, crisp, mint, bold, square, bloom, flower, ring, shutter)
PHOTOPRISM_APP_COLOR –app-color #19191a app background and splash screen COLOR
PHOTOPRISM_LEGAL_INFO –legal-info legal information TEXT, displayed in the page footer
PHOTOPRISM_LEGAL_URL –legal-url legal information URL
PHOTOPRISM_WALLPAPER_URI –wallpaper-uri login screen background image URI

Site Information

Environment CLI Flag Default Description
PHOTOPRISM_SITE_URL –site-url http://localhost:2342/ canonical site URL used in generated links and to determine HTTPS/TLS (scheme://host[:port])
PHOTOPRISM_SITE_AUTHOR –site-author site OWNER shown in the author meta tag
PHOTOPRISM_SITE_NAME –site-name short NAME for identifying this instance within a cluster optional
PHOTOPRISM_SITE_TITLE –site-title main TITLE shown in the web interface and meta tags
PHOTOPRISM_SITE_CAPTION –site-caption AI-Powered Digital Asset Management site CAPTION pro
PHOTOPRISM_SITE_DESCRIPTION –site-description longer DESCRIPTION shown in SEO and social meta tags optional
PHOTOPRISM_SITE_FAVICON –site-favicon custom favicon FILENAME for web browsers optional
PHOTOPRISM_SITE_PREVIEW –site-preview sharing preview image URL
PHOTOPRISM_CDN_URL –cdn-url content delivery network URL
PHOTOPRISM_CDN_VIDEO –cdn-video false streams videos over the specified CDN
PHOTOPRISM_CORS_ORIGIN –cors-origin origin URL from which browsers are allowed to perform cross-origin requests (leave blank to disable or use * to allow all)
PHOTOPRISM_CORS_HEADERS –cors-headers Accept, Accept-Ranges, Content-Disposition, Content-Encoding, Content-Range, Location one or more HEADERS that browsers should see when performing a cross-origin request
PHOTOPRISM_CORS_METHODS –cors-methods GET, HEAD, OPTIONS one or more METHODS that may be used when performing a cross-origin request

Cluster Configuration

Environment CLI Flag Default Description
PHOTOPRISM_CLUSTER_DOMAIN –cluster-domain cluster DOMAIN (lowercase DNS name; 1–63 chars)
PHOTOPRISM_CLUSTER_CIDR –cluster-cidr cluster CIDR for IP-based authorization, e.g. 10.0.0.0/8
PHOTOPRISM_CLUSTER_UUID –cluster-uuid cluster UUID (v4) to scope node credentials
PHOTOPRISM_CLUSTER_OIDC –cluster-oidc false use the cluster Portal as this instance’s OIDC login provider
PHOTOPRISM_PORTAL_URL –portal-url https://portal.${PHOTOPRISM_CLUSTER_DOMAIN} base URL of the cluster management portal
PHOTOPRISM_JOIN_TOKEN –join-token secret TOKEN required to join a cluster; min 24 chars
PHOTOPRISM_NODE_NAME –node-name node NAME (unique in cluster domain; [a-z0-9-]{1,32})
PHOTOPRISM_NODE_ROLE –node-role node ROLE (instance or service)
PHOTOPRISM_NODE_UUID –node-uuid node UUID (v7) that uniquely identifies this instance
PHOTOPRISM_NODE_CLIENT_ID –node-client-id node OAuth client ID (auto-assigned via join token)
PHOTOPRISM_NODE_CLIENT_SECRET –node-client-secret node OAuth client SECRET (auto-assigned via join token)
PHOTOPRISM_JWKS_URL –jwks-url JWKS endpoint URL provided by the cluster portal for JWT verification
PHOTOPRISM_JWKS_CACHE_TTL –jwks-cache-ttl 300 JWKS cache lifetime in SECONDS (default 300, max 3600)
PHOTOPRISM_JWT_SCOPE –jwt-scope config cluster vision metrics mcp users allowed JWT SCOPES (space separated). Leave empty to accept defaults
PHOTOPRISM_JWT_LEEWAY –jwt-leeway 60 JWT clock skew allowance in SECONDS (default 60, max 300)
PHOTOPRISM_PORTAL_OIDC_ISSUER –portal-oidc-issuer Portal OIDC OP issuer URL advertised in discovery and ID tokens (defaults to site-url)
PHOTOPRISM_PORTAL_OIDC_TTL –portal-oidc-ttl 300 Portal OIDC OP access/ID-token lifetime in SECONDS (default 300, max 900)
PHOTOPRISM_PORTAL_OIDC_CODE_TTL –portal-oidc-code-ttl 60 Portal OIDC OP authorization-code lifetime in SECONDS (default 60, max 300)
PHOTOPRISM_PORTAL_OIDC_DEFAULT_POLICY –portal-oidc-default-policy chooser Portal OIDC OP routing policy when a user has access to multiple instances (chooser or direct)
PHOTOPRISM_ADVERTISE_URL –advertise-url advertised URL for intra-cluster calls (scheme://host[:port])

Networking

Environment CLI Flag Default Description
PHOTOPRISM_HTTPS_PROXY –https-proxy proxy server URL to be used for outgoing connections optional
PHOTOPRISM_HTTPS_PROXY_INSECURE –https-proxy-insecure false ignores invalid HTTPS certificates when using a proxy
PHOTOPRISM_TRUSTED_PLATFORM –trusted-platform trusted client IP header NAME, e.g. when running behind a cloud provider load balancer
PHOTOPRISM_TRUSTED_PROXY –trusted-proxy 172.16.0.0/12 CIDR ranges or IPv4/v6 addresses from which reverse proxy headers can be trusted, separated by commas
PHOTOPRISM_PROXY_CLIENT_HEADER –proxy-client-header X-Forwarded-For proxy client IP header NAME, e.g. X-Forwarded-For, X-Client-IP, X-Real-IP, or CF-Connecting-IP
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_SERVICES_CIDR –services-cidr comma-separated CIDR ranges or IPs allowed for outbound service connections, e.g. 172.18.0.0/16

Web Server

Environment CLI Flag Default Description
PHOTOPRISM_DISABLE_TLS –disable-tls false disables HTTPS/TLS even if the site URL starts with https:// and a certificate is available
PHOTOPRISM_DEFAULT_TLS –default-tls false uses a self-signed HTTPS/TLS certificate if no other certificate is available
PHOTOPRISM_TLS_CERT –tls-cert public HTTPS certificate FILENAME (.crt), ignored for Unix domain sockets
PHOTOPRISM_TLS_KEY –tls-key private HTTPS key FILENAME (.key), ignored for Unix domain sockets
PHOTOPRISM_DISABLE_STS –disable-sts false disables HTTP Strict-Transport-Security (STS) header pro
PHOTOPRISM_STS_SECONDS –sts-seconds 31536000 TIME for the browser to remember that the site is to be accessed only via HTTPS (0 to disable) pro
PHOTOPRISM_STS_SUBDOMAINS –sts-subdomains false applies rule to all subdomains pro
PHOTOPRISM_STS_PRELOAD –sts-preload false allows submission to Google’s HSTS preload service pro
PHOTOPRISM_REQUEST_LIMIT –request-limit 500 maximum number of concurrent HTTP REQUESTS allowed from a single IP pro
PHOTOPRISM_REQUEST_INTERVAL –request-interval 5ms average DURATION between HTTP requests from a single IP (0-1000ms) pro
PHOTOPRISM_AUTH_LIMIT –auth-limit 60 maximum number of consecutive invalid access TOKENS from a single IP pro
PHOTOPRISM_AUTH_INTERVAL –auth-interval 10s average DURATION between invalid access tokens from a single IP (0-86400s) pro
PHOTOPRISM_LOGIN_LIMIT –login-limit 10 maximum number of consecutive failed LOGINS from a single IP pro
PHOTOPRISM_LOGIN_INTERVAL –login-interval 1m0s average DURATION between failed logins from a single IP (0-86400s) pro
PHOTOPRISM_IPS_LIMIT –ips-limit 3 maximum number of malicious request ATTEMPTS before a client IP is blocked (-1 to disable) pro
PHOTOPRISM_IPS_INTERVAL –ips-interval 1h0m0s average DURATION between malicious request attempts from a single IP (0-86400s) pro
PHOTOPRISM_HTTP_CSP –http-csp HTTP Content-Security-Policy (CSP) HEADER pro
PHOTOPRISM_HTTP_CTO –http-cto nosniff HTTP X-Content-Type-Options HEADER pro
PHOTOPRISM_HTTP_COOP –http-coop same-origin HTTP Cross-Origin-Opener-Policy (COOP) HEADER pro
PHOTOPRISM_HTTP_REFERRER_POLICY –http-referrer-policy same-origin HTTP Referrer-Policy HEADER pro
PHOTOPRISM_HTTP_FRAME_OPTIONS –http-frame-options DENY HTTP X-Frame-Options HEADER pro
PHOTOPRISM_HTTP_MODE –http-mode Web server MODE (debug, release, test)
PHOTOPRISM_HTTP_COMPRESSION –http-compression Web server compression METHODS as a comma-separated preference list (e.g. “zstd,gzip”; supported: gzip, zstd, none)
PHOTOPRISM_HTTP_HEADER_TIMEOUT –http-header-timeout 15s timeout for reading request headers as DURATION
PHOTOPRISM_HTTP_HEADER_BYTES –http-header-bytes 1048576 maximum request header size in BYTES
PHOTOPRISM_HTTP_IDLE_TIMEOUT –http-idle-timeout 3m0s timeout for idle keep-alive connections as DURATION
PHOTOPRISM_HTTP_CACHE_PUBLIC –http-cache-public false allows static content to be cached by a CDN or caching proxy
PHOTOPRISM_HTTP_CACHE_MAXAGE –http-cache-maxage 2592000 time in SECONDS until cached content expires
PHOTOPRISM_HTTP_VIDEO_MAXAGE –http-video-maxage 21600 time in SECONDS until cached videos expire
PHOTOPRISM_HTTP_HOST –http-host 0.0.0.0 Web server IP address or Unix domain socket, e.g. unix:/var/run/photoprism.sock?force=true&mode=660
PHOTOPRISM_HTTP_PORT –http-port 2342 Web server port NUMBER, ignored for Unix domain sockets
PHOTOPRISM_HTTP_HOSTNAME –http-hostname serve requests for this HOSTNAME only pro

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_TIMEOUT –database-timeout 15 timeout in SECONDS for establishing a database connection (1-60)
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 Conversion

Environment CLI Flag Default Description
PHOTOPRISM_FFMPEG_BIN –ffmpeg-bin ffmpeg FFmpeg COMMAND for video transcoding and thumbnail extraction
PHOTOPRISM_FFMPEG_ENCODER –ffmpeg-encoder libx264 FFmpeg AVC video encoder NAME
PHOTOPRISM_FFMPEG_SIZE –ffmpeg-size 4096 encoding resolution limit in PIXELS (720-7680)
PHOTOPRISM_FFMPEG_QUALITY –ffmpeg-quality 50 encoding QUALITY (1-100, where 100 is almost lossless)
PHOTOPRISM_FFMPEG_BITRATE –ffmpeg-bitrate 60 bitrate LIMIT in Mbps for forced transcoding of non-AVC videos (1-960; -1 to disable)
PHOTOPRISM_FFMPEG_PRESET –ffmpeg-preset fast FFmpeg compression PRESET when using an encoder that supports it, e.g. fast, medium, or slow
PHOTOPRISM_FFMPEG_DEVICE –ffmpeg-device FFmpeg device PATH when using a hardware encoder that supports it as parameter
PHOTOPRISM_FFMPEG_MAP_VIDEO –ffmpeg-map-video 0:v:0 transcoding video stream MAP
PHOTOPRISM_FFMPEG_MAP_AUDIO –ffmpeg-map-audio 0:a:0? transcoding audio stream MAP
PHOTOPRISM_FFMPEG_EXCLUDE, PHOTOPRISM_FFMPEG_BLACKLIST –ffmpeg-exclude magy, vfw container and codec FORMATS not to be processed by FFmpeg, separated by commas
PHOTOPRISM_EXIFTOOL_BIN –exiftool-bin exiftool ExifTool COMMAND for extracting metadata
PHOTOPRISM_SIPS_BIN –sips-bin sips Sips COMMAND for media file conversion macOS only
PHOTOPRISM_SIPS_EXCLUDE, PHOTOPRISM_SIPS_BLACKLIST –sips-exclude avif, avifs, thm file EXTENSIONS not to be used with Sips macOS only
PHOTOPRISM_DARKTABLE_BIN –darktable-bin darktable-cli Darktable CLI COMMAND for RAW to JPEG conversion
PHOTOPRISM_DARKTABLE_EXCLUDE, PHOTOPRISM_DARKTABLE_BLACKLIST –darktable-exclude thm file EXTENSIONS not to be used with Darktable
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_EXCLUDE, PHOTOPRISM_RAWTHERAPEE_BLACKLIST –rawtherapee-exclude dng, thm file EXTENSIONS not to be used with RawTherapee
PHOTOPRISM_IMAGEMAGICK_BIN –imagemagick-bin convert ImageMagick CLI COMMAND for image file conversion
PHOTOPRISM_IMAGEMAGICK_EXCLUDE, PHOTOPRISM_IMAGEMAGICK_BLACKLIST –imagemagick-exclude heif, heic, heics, avif, avifs, jxl, thm file EXTENSIONS not to be used with ImageMagick
PHOTOPRISM_HEIFCONVERT_BIN –heifconvert-bin heif-dec libheif HEIC image conversion COMMAND
PHOTOPRISM_RSVGCONVERT_BIN –rsvgconvert-bin rsvg-convert librsvg SVG graphics conversion COMMAND pro
PHOTOPRISM_HEIFCONVERT_ORIENTATION –heifconvert-orientation keep Exif ORIENTATION of images generated with libheif (keep, reset)

Security Tokens

Environment CLI Flag Default Description
PHOTOPRISM_DOWNLOAD_TOKEN –download-token DEFAULT download URL token for originals (leave blank for a random value)
PHOTOPRISM_PREVIEW_TOKEN –preview-token DEFAULT thumbnail and video streaming URL token (leave blank for a random value)

Preview Images

Environment CLI Flag Default Description
PHOTOPRISM_THUMB_LIBRARY –thumb-library auto image processing LIBRARY to be used for generating thumbnails (auto, vips)
PHOTOPRISM_THUMB_COLOR –thumb-color auto standard color PROFILE for thumbnails (auto, preserve, srgb, none)
PHOTOPRISM_THUMB_SIZE –thumb-size 1920 maximum size of pre-generated thumbnails in PIXELS (720-7680)
PHOTOPRISM_THUMB_SIZE_UNCACHED –thumb-size-uncached 5120 maximum size of thumbnails generated on demand in PIXELS (720-7680)
PHOTOPRISM_THUMB_UNCACHED –thumb-uncached false generates missing thumbnails on demand (high memory and cpu usage)

Image Quality

Environment CLI Flag Default Description
PHOTOPRISM_JPEG_QUALITY –jpeg-quality 83 higher values increase the image QUALITY and file size (25-100)
PHOTOPRISM_JPEG_SIZE –jpeg-size 7680 maximum size of generated JPEG images in PIXELS (720-30000)
PHOTOPRISM_PNG_SIZE –png-size 7680 maximum size of generated PNG images in PIXELS (720-30000)

Computer Vision

Environment CLI Flag Default Description
PHOTOPRISM_VISION_YAML –vision-yaml computer vision model configuration FILENAME optional
PHOTOPRISM_VISION_API –vision-api false enables the computer vision API endpoints under /api/v1/vision (requires authorization)
PHOTOPRISM_VISION_URI –vision-uri vision service base URI, e.g. https://example.com/api/v1/vision (leave blank to disable)
PHOTOPRISM_VISION_KEY –vision-key vision service access TOKEN optional
PHOTOPRISM_VISION_SCHEDULE –vision-schedule vision worker SCHEDULE for background processing (e.g. “0 12 * * *” for daily at noon) or at a random time (daily, weekly)
PHOTOPRISM_VISION_FILTER –vision-filter public:true vision worker search FILTER applied to scheduled runs (same syntax as photoprism vision run)
PHOTOPRISM_DETECT_NSFW –detect-nsfw false flags newly added pictures as private if they might be offensive (uses the configured NSFW model; built-in TensorFlow by default)

Face Recognition

A reasonable range for the similarity distance is between 0.60 and 0.85, with higher values resulting in more aggressive clustering and more false positives. To cluster a smaller number of faces, reduce the core to 3 or 2 similar faces. After changing any of the clustering parameters, it is strongly recommended that you run the “photoprism faces reset” command in a terminal to remove existing clusters and mappings, as otherwise inconsistencies may result in unexpected behavior or errors.

We recommend that only advanced users change these parameters:

Environment CLI Flag Default Description
PHOTOPRISM_FACE_ENGINE –face-engine auto face detection engine NAME (auto, onnx)
PHOTOPRISM_FACE_ENGINE_THREADS –face-engine-threads 0 face detection thread COUNT (0 uses half the available CPU cores)
PHOTOPRISM_FACE_SIZE –face-size 25 minimum size of faces in PIXELS (20-10000)
PHOTOPRISM_FACE_SCORE –face-score 9 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 60 minimum size of automatically clustered faces in PIXELS (20-10000)
PHOTOPRISM_FACE_CLUSTER_SCORE –face-cluster-score 20 minimum QUALITY score of automatically clustered faces (1-100)
PHOTOPRISM_FACE_CLUSTER_CORE –face-cluster-core 4 NUMBER of faces forming a cluster core (1-100)
PHOTOPRISM_FACE_CLUSTER_DIST –face-cluster-dist 0.64 similarity DISTANCE of faces forming a cluster core (0.1-1.5)
PHOTOPRISM_FACE_CLUSTER_RADIUS –face-cluster-radius 0.42 maximum cluster RADIUS accepted for automatic matches (0.1-1.5)
PHOTOPRISM_FACE_COLLISION_DIST –face-collision-dist 0.05 minimum collision discrimination DISTANCE (0.01-1)
PHOTOPRISM_FACE_EPSILON_DIST –face-epsilon-dist 0.01 collision tolerance DELTA appended to max match distances (0.001-0.1)
PHOTOPRISM_FACE_MATCH_DIST –face-match-dist 0.4 similarity OFFSET for matching faces with existing clusters (0.1-1.5)
PHOTOPRISM_FACE_SKIP_CHILDREN –face-skip-children false skips automatic matching of child face embeddings
PHOTOPRISM_FACE_ALLOW_BACKGROUND –face-allow-background false allows matching of probable background embeddings

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 FILENAME daemon-mode only
PHOTOPRISM_LOG_FILENAME –log-filename server log FILENAME 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, 900-1250, and 2000-2100)
PHOTOPRISM_GID 0 run with a specific group id after initialization, can optionally be used together with PHOTOPRISM_UID (supported: 0, 33, 44, 50-99, 105, 109, 115, 116, 500-600, 900-1250, and 2000-2100)
PHOTOPRISM_UMASK 0002 file-creation mode (default: u=rwx,g=rwx,o=rx)
PHOTOPRISM_INIT https tensorflow run/install on first startup (common options: update tensorflow https intel gpu davfs yt-dlp)
PHOTOPRISM_DISABLE_CHOWN false disable updating storage permissions via chmod and chown on startup

PhotoPrism® Documentation

For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide: