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_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 automatically redirect unauthenticated users to the configured identity provider
PHOTOPRISM_OIDC_REGISTER --oidc-register allow 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_WEBDAV --oidc-webdav allow new OpenID Connect users to use WebDAV when they have a role that allows it
PHOTOPRISM_DISABLE_OIDC --disable-oidc disable 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 skip SSL/TLS certificate verification when using LDAPS pro
PHOTOPRISM_LDAP_CHASE --ldap-chase automatically chase referrals when there are multiple LDAP servers pro
PHOTOPRISM_LDAP_CHASE_INSECURE --ldap-chase-insecure skip SSL/TLS certificate verification when chasing referrals pro
PHOTOPRISM_LDAP_SYNC --ldap-sync update 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, 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 disable 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 allow 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 disable 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 disable debug mode and log startup warnings and errors only
PHOTOPRISM_DEBUG --debug enable debug mode for development and troubleshooting
PHOTOPRISM_TRACE --trace enable trace mode to display all debug and trace logs

Storage

Environment CLI Flag Default Description
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 load 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_STORAGE_PATH --storage-path writable storage PATH for sidecar, cache, and database files
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_IMPORT_ALLOW --import-allow restrict imports to these file types (comma-separated list of EXTENSIONS; leave blank to allow all)
PHOTOPRISM_UPLOAD_NSFW --upload-nsfw allow uploads that might be offensive (detecting unsafe content requires TensorFlow)
PHOTOPRISM_UPLOAD_ALLOW --upload-allow restrict uploads to these file types (comma-separated list of EXTENSIONS; leave blank to allow all)
PHOTOPRISM_UPLOAD_ARCHIVES --upload-archives allow 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

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 create YAML sidecar files to back up picture metadata

Usage

Environment CLI Flag Default Description
PHOTOPRISM_USAGE_INFO --usage-info display 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 create regular backups based on the configured schedule
PHOTOPRISM_BACKUP_ALBUMS --backup-albums true create YAML files to back up album metadata

Indexing

Environment CLI Flag Default Description
PHOTOPRISM_INDEX_WORKERS, PHOTOPRISM_WORKERS --index-workers 4 maximum NUMBER of indexing workers, default depends on the number of physical 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 disable features that require write permission for the originals folder
PHOTOPRISM_EXPERIMENTAL --experimental enable new features that may be incomplete or unstable
PHOTOPRISM_DISABLE_SETTINGS --disable-settings disable the settings user interface and server API, e.g. in combination with public mode
PHOTOPRISM_DISABLE_BACKUPS --disable-backups prevent database and album backups as well as YAML sidecar files from being created
PHOTOPRISM_DISABLE_RESTART --disable-restart prevent admins from restarting the server through the user interface
PHOTOPRISM_DISABLE_WEBDAV --disable-webdav prevent other apps from accessing PhotoPrism as a shared network drive
PHOTOPRISM_DISABLE_PLACES --disable-places disable interactive world maps and reverse geocoding
PHOTOPRISM_DISABLE_TENSORFLOW --disable-tensorflow disable features depending on TensorFlow, e.g. image classification and face recognition
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 metadata extraction with ExifTool (required for full Video, Live Photo, and XMP support)
PHOTOPRISM_DISABLE_VIPS --disable-vips disable image processing and conversion with libvips
PHOTOPRISM_DISABLE_SIPS --disable-sips disable file conversion using the sips command under macOS
PHOTOPRISM_DISABLE_DARKTABLE --disable-darktable disable conversion of RAW images with Darktable
PHOTOPRISM_DISABLE_RAWTHERAPEE --disable-rawtherapee disable conversion of RAW images with RawTherapee
PHOTOPRISM_DISABLE_IMAGEMAGICK --disable-imagemagick disable conversion of image files with ImageMagick
PHOTOPRISM_DISABLE_HEIFCONVERT --disable-heifconvert disable conversion of HEIC images with libheif
PHOTOPRISM_DISABLE_RSVGCONVERT --disable-rsvgconvert disable conversion of SVG graphics with librsvg pro
PHOTOPRISM_DISABLE_VECTORS --disable-vectors disable vector graphics support pro
PHOTOPRISM_DISABLE_JPEGXL --disable-jpegxl disable JPEG XL file format support
PHOTOPRISM_DISABLE_RAW --disable-raw disable indexing and conversion of RAW images
PHOTOPRISM_RAW_PRESETS --raw-presets enables applying user presets when converting RAW images (reduces performance)
PHOTOPRISM_EXIF_BRUTEFORCE --exif-bruteforce always perform 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_APP_NAME --app-name progressive web app NAME when installed on a device
PHOTOPRISM_APP_MODE --app-mode standalone progressive web app MODE (fullscreen, standalone, minimal-ui, browser)
PHOTOPRISM_APP_ICON --app-icon home screen ICON (logo, app, crisp, mint, bold, square)
PHOTOPRISM_APP_COLOR --app-color #000000 splash screen COLOR code
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 public site URL pro
PHOTOPRISM_SITE_AUTHOR --site-author site OWNER, copyright, or artist
PHOTOPRISM_SITE_TITLE --site-title site TITLE
PHOTOPRISM_SITE_CAPTION --site-caption AI-Powered Digital Asset Management site CAPTION pro
PHOTOPRISM_SITE_DESCRIPTION --site-description site DESCRIPTION optional
PHOTOPRISM_SITE_FAVICON --site-favicon site favicon FILENAME optional
PHOTOPRISM_SITE_PREVIEW --site-preview sharing preview image URL
PHOTOPRISM_CDN_URL --cdn-url content delivery network URL
PHOTOPRISM_CDN_VIDEO --cdn-video stream 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

Proxy Servers

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 ignore invalid HTTPS certificates when using a proxy
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_PROTO_HEADER --proxy-proto-header "X-Forwarded-Proto" proxy protocol header NAME
PHOTOPRISM_PROXY_PROTO_HTTPS --proxy-proto-https "https" forwarded HTTPS protocol NAME

Web Server

Environment CLI Flag Default Description
PHOTOPRISM_DISABLE_TLS --disable-tls disable HTTPS/TLS even if the site URL starts with https:// and a certificate is available
PHOTOPRISM_DEFAULT_TLS --default-tls default to 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 disable 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 rule applies to all subdomains as well pro
PHOTOPRISM_STS_PRELOAD --sts-preload submit 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_XSS_PROTECTION --http-xss-protection 1; mode=block HTTP X-XSS-Protection HEADER pro
PHOTOPRISM_HTTP_MODE --http-mode Web server MODE (debug, release, test)
PHOTOPRISM_HTTP_COMPRESSION --http-compression Web server compression METHOD (gzip, none)
PHOTOPRISM_HTTP_CACHE_PUBLIC --http-cache-public allow 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 encoder NAME
PHOTOPRISM_FFMPEG_SIZE --ffmpeg-size 4096 maximum video size in PIXELS (720-7680)
PHOTOPRISM_FFMPEG_BITRATE --ffmpeg-bitrate 60 maximum video BITRATE in Mbps
PHOTOPRISM_FFMPEG_MAP_VIDEO --ffmpeg-map-video 0:v:0 video STREAMS that should be transcoded
PHOTOPRISM_FFMPEG_MAP_AUDIO --ffmpeg-map-audio 0:a:0? audio STREAMS that should be transcoded
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, imaging, vips)
PHOTOPRISM_THUMB_COLOR --thumb-color auto standard color PROFILE for thumbnails (auto, preserve, srgb, none)
PHOTOPRISM_THUMB_FILTER --thumb-filter auto downscaling filter NAME (imaging best to worst: blackman, lanczos, cubic, linear, nearest)
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 generate 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 enable computer vision service API endpoints under /api/v1/vision (requires authorized access token)
PHOTOPRISM_VISION_URI --vision-uri remote computer vision service URI, e.g. https://example.com/api/v1/vision (leave blank to disable)
PHOTOPRISM_VISION_KEY --vision-key remote computer vision service access TOKEN optional
PHOTOPRISM_DETECT_NSFW --detect-nsfw flag newly added pictures as private if they might be offensive (requires TensorFlow)

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. It is strongly recommended that you run the "photoprism faces reset" command in a terminal to remove existing clusters and mappings after changing any of the clustering parameters, 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_SIZE --face-size 50 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 80 minimum size of automatically clustered faces in PIXELS (20-10000)
PHOTOPRISM_FACE_CLUSTER_SCORE --face-cluster-score 15 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_MATCH_DIST --face-match-dist 0.46 similarity OFFSET for matching faces with existing clusters (0.1-1.5)

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)
PHOTOPRISM_DISABLE_CHOWN false disable updating storage permissions via chmod and chown on startup

PhotoPrism® Documentation

For detailed information on specific product features, services, and related resources, see our Knowledge Base, or read the User Guide for help using the web user interface: