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_PROMPT | –oidc-prompt | authorization PROMPT for single sign-on via OpenID Connect (login, select_account, consent) |
|
| 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_LOGOUT | –oidc-logout | false | ends the provider session on sign-out via OpenID Connect RP-initiated logout |
| 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, manager, user, contributor, viewer, 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, contributor, viewer, or 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) |
| PHOTOPRISM_DOWNLOAD_TOKEN | –download-token | shared static TOKEN for permanent download URLs (leave blank to accept signed tokens only) |
|
| PHOTOPRISM_DOWNLOAD_TOKEN_MAXAGE | –download-token-maxage | 3600 | signed download token lifetime in SECONDS (minimum 900) |
| PHOTOPRISM_PREVIEW_TOKEN | –preview-token | shared static TOKEN for thumbnail and video streaming URLs (leave blank for an automatic value) |
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_CASE | –storage-case | auto | file name case MODE of storage, also used for originals of unknown mode (auto, sensitive, insensitive) |
| PHOTOPRISM_STORAGE_FREE | –storage-free | -1 | minimum free storage in PERCENT required for indexing, importing, and uploads (1-99; -1 to disable) |
| PHOTOPRISM_CONFIG_PATH | –config-path | config storage PATH or options.yml filename (values override CLI flags and environment variables) |
|
| PHOTOPRISM_DEFAULTS_YAML | –defaults-yaml | /etc/photoprism/defaults.yml | default config FILENAME (values do not override CLI flags or environment variables) |
| PHOTOPRISM_ORIGINALS_PATH | –originals-path | storage PATH of your original media files (photos and videos) |
|
| PHOTOPRISM_ORIGINALS_CASE | –originals-case | auto | file name case MODE of originals (auto, sensitive, insensitive) |
| PHOTOPRISM_ORIGINALS_LIMIT | –originals-limit | 5000 | maximum size of a single media file in MB (-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 (skips NSFW screening) |
| PHOTOPRISM_UPLOAD_ALLOW | –upload-allow | further restricts web uploads to these file types (comma-separated list of EXTENSIONS) |
|
| PHOTOPRISM_UPLOAD_ARCHIVES | –upload-archives | false | allows upload of zip archives (will be extracted before import) |
| PHOTOPRISM_UPLOAD_LIMIT | –upload-limit | 5000 | maximum total size of web uploads in MB (-1 to disable) |
| PHOTOPRISM_UPLOAD_MAXAGE | –upload-maxage | 604800 | maximum age of staged uploads that were not imported in SECONDS (86400-3153600000; -1 to keep them) |
| 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 |
| 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, glass, neon, rainbow) |
|
| 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 | short CAPTION or tagline shown alongside the title 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 allowed to make cross-origin requests (leave blank to disable, * 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 ranges for IP-based authorization, separated by commas, 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_JWT_ROTATE_DAYS | –jwt-rotate-days | 90 | portal JWT signing key lifetime in DAYS, -1 to rotate manually only |
| 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, 127.0.0.0/8, ::1 | 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 or TLS email is configured |
| PHOTOPRISM_DEFAULT_TLS | –default-tls | false | uses a self-signed HTTPS/TLS certificate if no other certificate is available |
| PHOTOPRISM_TLS_EMAIL | –tls-email | EMAIL address to obtain an HTTPS certificate from Let’s Encrypt, which must reach port 443 |
|
| PHOTOPRISM_TLS_CERT | –tls-cert | public HTTPS certificate FILENAME (.crt), ignored for Unix domain sockets and with automatic HTTPS |
|
| PHOTOPRISM_TLS_KEY | –tls-key | private HTTPS key FILENAME (.key), ignored for Unix domain sockets and with automatic HTTPS |
|
| 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 (-1 to disable) pro |
| PHOTOPRISM_REQUEST_INTERVAL | –request-interval | 5ms | average DURATION between HTTP requests from a single IP (1-60000ms) pro |
| PHOTOPRISM_AUTH_LIMIT | –auth-limit | 60 | maximum number of consecutive invalid access TOKENS from a single IP (-1 to disable) pro |
| PHOTOPRISM_AUTH_INTERVAL | –auth-interval | 10s | average DURATION between invalid access tokens from a single IP (1-3600s) pro |
| PHOTOPRISM_LOGIN_LIMIT | –login-limit | 10 | maximum number of consecutive failed LOGINS from a single IP (-1 to disable) pro |
| PHOTOPRISM_LOGIN_INTERVAL | –login-interval | 1m0s | average DURATION between failed logins from a single IP (1-3600s) 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 (1-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 | enabled compression METHODS in order of preference (gzip, zstd, none), e.g. “zstd,gzip” |
|
| 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-15360) |
| 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, also limits the NVIDIA peak bitrate (1-960; -1 to disable) |
| PHOTOPRISM_FFMPEG_FISHEYE_FOV | –ffmpeg-fisheye-fov | 190 | field of view in DEGREES for dewarping fisheye 360° originals (90-360) |
| 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_CONVERT_TIMEOUT | –convert-timeout | 10 | timeout in MINUTES for converting still images, documents, and RAW files (-1 to disable) |
| PHOTOPRISM_TRANSCODE_TIMEOUT | –transcode-timeout | -1 | time in MINUTES after which transcoding a video is given up (disabled by default) |
| 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) |
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-15360) |
| PHOTOPRISM_THUMB_SIZE_UNCACHED | –thumb-size-uncached | 7680 | maximum size of thumbnails generated on demand in PIXELS (720-15360) |
| PHOTOPRISM_THUMB_SIZE_FACE | –thumb-size-face | 4096 | maximum size of face crop sources rendered on demand in PIXELS (720-15360; 0 to disable) |
| 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 | 15360 | maximum size of generated JPEG images in PIXELS (720-30000) |
| PHOTOPRISM_PNG_SIZE | –png-size | 15360 | 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 in cron format (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_ONNX_PROVIDER | –onnx-provider | cpu | execution PROVIDER for ONNX inference (cpu, cuda), falls back to the CPU when unavailable |
| PHOTOPRISM_LABELS_MODEL | –labels-model | auto | image classification MODE (auto, none) |
| PHOTOPRISM_NSFW_MODEL | –nsfw-model | auto | NSFW detection MODE (auto, none, labels) |
| PHOTOPRISM_DETECT_NSFW | –detect-nsfw | false | flags newly added pictures as private if they might be offensive (uses the configured NSFW model) |
Face Recognition
Changing the face model requires running photoprism faces migrate. Leaving the distance thresholds unset is recommended since they are calibrated for the configured face model. A range that fits one embedding model does not transfer to another. Higher values cluster more aggressively and produce more false positives. After changing any of the clustering parameters or after migration, run photoprism faces update --force: it clusters what is unassigned and matches every face against the clusters again, so an automatically matched face may end up in a different cluster while a face that you assigned manually keeps its assignment.
We recommend that only advanced users change the detector, model, or clustering parameters:
| Environment | CLI Flag | Default | Description |
|---|---|---|---|
| PHOTOPRISM_XMP_FACES | –xmp-faces | false | imports face regions and names from XMP metadata as people markers |
| PHOTOPRISM_FACE_RUN | –face-run | auto | WHEN face detection and recognition should run (auto, always, on-index, newly-indexed, on-schedule, on-demand, manual, never) |
| PHOTOPRISM_FACE_DETECTOR | –face-detector | yunet | face detection model NAME (auto, yunet, none), derived from the face model unless named |
| PHOTOPRISM_FACE_DETECTOR_THREADS | –face-detector-threads | auto | face detection thread COUNT per indexing worker, derived from the CPU cores when unset |
| PHOTOPRISM_FACE_SIZE | –face-size | 25 | minimum size of faces in PIXELS (10-10000) |
| PHOTOPRISM_FACE_SIZE_RETRY | –face-size-retry | 10 (20 where a crop can reach no further than 1920, off at 720) | minimum size of faces in PIXELS when a picture would otherwise have none, -1 to disable |
| PHOTOPRISM_FACE_SCORE | –face-score | 65 | minimum face QUALITY score (1-100; -1 to disable), calibrated per detector when unset |
| PHOTOPRISM_FACE_MIGRATE_SIZE | –face-migrate-size | 10 | minimum size of faces in PIXELS when a migration re-detects them |
| PHOTOPRISM_FACE_MIGRATE_SCORE | –face-migrate-score | 50 | minimum face QUALITY score (1-100) while a migration re-detects them, -1 disables the check |
| PHOTOPRISM_FACE_OVERLAP | –face-overlap | 42 | face area overlap threshold in PERCENT (1-100) |
| PHOTOPRISM_FACE_MODEL | –face-model | sface | face embedding model NAME (auto, sface, none), changed with photoprism faces migrate |
| PHOTOPRISM_FACE_MODEL_THREADS | –face-model-threads | auto | face embedding thread COUNT, derived from the CPU cores when unset |
| PHOTOPRISM_FACE_CLUSTER_SIZE | –face-cluster-size | 112 | minimum size of automatically clustered faces in embedding source PIXELS (20-10000), calibrated per face model when unset |
| PHOTOPRISM_FACE_CLUSTER_SCORE | –face-cluster-score | 85 | minimum QUALITY score of automatically clustered faces (1-100; -1 to disable), calibrated per detector when unset |
| PHOTOPRISM_FACE_CLUSTER_CORE | –face-cluster-core | 5 | NUMBER of faces forming a cluster core (2-100) |
| PHOTOPRISM_FACE_CLUSTER_CORE_RETRY | –face-cluster-core-retry | 4 (off where face-cluster-core is below 5) | NUMBER of faces forming a cluster core in a second pass over what matching left unclustered, -1 to disable |
| PHOTOPRISM_FACE_CLUSTER_DIST | –face-cluster-dist | 0.72 | similarity DISTANCE of faces forming a cluster core (collision distance to 1.25), calibrated per face model when unset |
| PHOTOPRISM_FACE_CLUSTER_RADIUS | –face-cluster-radius | 0.7 | maximum cluster RADIUS accepted for automatic matches, calibrated per face model when unset; radius plus match distance may not exceed 1.25 |
| PHOTOPRISM_FACE_CLUSTER_PERCENTILE | –face-cluster-percentile | 95 | PERCENTILE of member distances that determines a cluster’s radius (1-100; 100 uses the maximum) |
| PHOTOPRISM_FACE_MATCH_DIST | –face-match-dist | 0.25 | similarity OFFSET for matching faces with existing clusters, calibrated per face model when unset; radius plus match distance may not exceed 1.25 |
| PHOTOPRISM_FACE_MATCH_MARGIN | –face-match-margin | 0.01 | minimum DISTANCE by which the best matching cluster must beat the runner-up (-1 to disable) |
| PHOTOPRISM_FACE_COLLISION_DIST | –face-collision-dist | 0.05 | minimum collision discrimination DISTANCE (greater than 0, up to 1), the same for every face model |
| PHOTOPRISM_FACE_EPSILON_DIST | –face-epsilon-dist | 0.001 | collision tolerance DELTA added to maximum match distances (up to 0.01), the same for every face model |
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 |
