Authentication

Environment CLI Flag Default Description
PHOTOPRISM_AUTH_MODE --auth-mode password authentication MODE (public, password)
PHOTOPRISM_ADMIN_USER --admin-user admin admin login USERNAME
PHOTOPRISM_ADMIN_PASSWORD --admin-password initial admin PASSWORD (8-72 characters)
PHOTOPRISM_SESSION_MAXAGE --session-maxage 1209600 time in SECONDS until API sessions expire automatically (-1 to disable)
PHOTOPRISM_SESSION_TIMEOUT --session-timeout 604800 time in SECONDS until API sessions expire due to inactivity (-1 to disable)
PHOTOPRISM_LOGIN_URI --login-uri user login URI pro
PHOTOPRISM_REGISTER_URI --register-uri user registration URI pro
PHOTOPRISM_PASSWORD_LENGTH --password-length 8 minimum password LENGTH in characters pro
PHOTOPRISM_PASSWORD_RESET_URI --password-reset-uri forgot password URI pro
PHOTOPRISM_LDAP_URI --ldap-uri LDAP directory URI e.g. ldaps://example.com:636 for LDAP over SSL pro
PHOTOPRISM_LDAP_CERT --ldap-cert LDAP directory SSL certificate FILE (.pem) pro
PHOTOPRISM_LDAP_INSECURE --ldap-insecure skip SSL 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 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 by default pro
PHOTOPRISM_LDAP_WEBDAV_DN --ldap-webdav-dn custom LDAP attribute DN to allow 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

Logging

Environment CLI Flag Default Description
PHOTOPRISM_LOG_LEVEL --log-level info log message verbosity LEVEL (trace, debug, info, warning, error, fatal, panic)
PHOTOPRISM_AUDIT_LEVEL --audit-level warning audit log recording LEVEL (debug, info, warning, error, fatal, panic) pro
PHOTOPRISM_DEBUG --debug enable debug mode, show non-essential log messages
PHOTOPRISM_TRACE --trace enable trace mode, show all log messages

Storage

Environment CLI Flag Default Description
PHOTOPRISM_CONFIG_PATH --config-path config storage PATH, values in options.yml override CLI flags and environment variables if present
PHOTOPRISM_DEFAULTS_YAML --defaults-yaml /etc/photoprism/defaults.yml load config defaults from FILE if exists, does not override CLI flags and environment variables
PHOTOPRISM_ORIGINALS_PATH --originals-path storage PATH of your original media files (photos and videos)
PHOTOPRISM_ORIGINALS_LIMIT --originals-limit 1000 maximum size of media files in MB (1-100000; -1 to disable)
PHOTOPRISM_RESOLUTION_LIMIT --resolution-limit 150 maximum resolution of media files in MEGAPIXELS (1-900; -1 to disable)
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_SIDECAR_PATH --sidecar-path custom relative or absolute sidecar PATH optional
PHOTOPRISM_BACKUP_PATH --backup-path custom backup PATH for index backup files optional
PHOTOPRISM_CACHE_PATH --cache-path custom cache PATH for sessions and thumbnail files optional
PHOTOPRISM_IMPORT_PATH --import-path base PATH from which files can be imported to originals optional
PHOTOPRISM_IMPORT_DEST --import-dest relative originals PATH to which the files should be imported by default optional
PHOTOPRISM_ASSETS_PATH --assets-path assets PATH containing static resources like icons, models, and translations
PHOTOPRISM_CUSTOM_ASSETS_PATH --custom-assets-path assets PATH for custom templates and wallpapers pro
PHOTOPRISM_TEMP_PATH --temp-path temporary file PATH optional

Index Workers

Environment CLI Flag Default Description
PHOTOPRISM_WORKERS --workers 4 maximum NUMBER of indexing workers, default depends on the number of physical cores
PHOTOPRISM_WAKEUP_INTERVAL --wakeup-interval 15m0s DURATION between worker runs required for face recognition and index maintenance (1-86400s)
PHOTOPRISM_AUTO_INDEX --auto-index 300 WebDAV auto index safety delay in SECONDS (-1 to disable)
PHOTOPRISM_AUTO_IMPORT --auto-import 180 WebDAV auto import safety delay in SECONDS (-1 to disable)

Feature Flags

Environment CLI Flag Default Description
PHOTOPRISM_READONLY --read-only disable import, upload, delete, and all other operations that require write permissions
PHOTOPRISM_EXPERIMENTAL --experimental enable experimental features
PHOTOPRISM_DISABLE_SETTINGS --disable-settings disable settings UI and API
PHOTOPRISM_DISABLE_RESTART --disable-restart disable restarting the server from the user interface
PHOTOPRISM_DISABLE_BACKUPS --disable-backups disable backing up albums and photo metadata to YAML files
PHOTOPRISM_DISABLE_WEBDAV --disable-webdav disable built-in WebDAV server
PHOTOPRISM_DISABLE_PLACES --disable-places disable reverse geocoding and maps
PHOTOPRISM_DISABLE_TENSORFLOW --disable-tensorflow disable all features depending on TensorFlow
PHOTOPRISM_DISABLE_FACES --disable-faces disable face detection and recognition (requires TensorFlow)
PHOTOPRISM_DISABLE_CLASSIFICATION --disable-classification disable image classification (requires TensorFlow)
PHOTOPRISM_DISABLE_SIPS --disable-sips disable conversion of media files with Sips macOS only
PHOTOPRISM_DISABLE_FFMPEG --disable-ffmpeg disable video transcoding and thumbnail extraction with FFmpeg
PHOTOPRISM_DISABLE_EXIFTOOL --disable-exiftool disable creating JSON metadata sidecar files with ExifTool
PHOTOPRISM_DISABLE_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
PHOTOPRISM_DETECT_NSFW --detect-nsfw automatically flag photos as private that MAY be offensive (requires TensorFlow)
PHOTOPRISM_UPLOAD_NSFW --upload-nsfw allow uploads that MAY be offensive (no effect without TensorFlow)

Customization

Environment CLI Flag Default Description
PHOTOPRISM_DEFAULT_LOCALE --default-locale en standard user interface language CODE
PHOTOPRISM_DEFAULT_THEME --default-theme standard user interface theme NAME
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_CDN_URL --cdn-url content delivery network URL
PHOTOPRISM_CDN_VIDEO --cdn-video stream videos over the specified CDN
PHOTOPRISM_PORTAL_URL --portal-url PhotoPrism® Portal Server URL (optional) pro
PHOTOPRISM_MICRO_URL --micro-url PhotoPrism® Micro API URL (optional) pro
PHOTOPRISM_SITE_URL --site-url https://privatecloud.photos:2342/ 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_PREVIEW --site-preview sharing preview image URL

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 even if a certificate is available
PHOTOPRISM_TLS_CERT --tls-cert public HTTPS certificate FILE (.crt)
PHOTOPRISM_TLS_KEY --tls-key private HTTPS key FILE (.key)
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_LOGIN_LIMIT --login-limit 10 maximum number of consecutive failed LOGIN ATTEMPTS from a single IP pro
PHOTOPRISM_LOGIN_INTERVAL --login-interval 1m0s average DURATION between failed LOGIN attempts 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_MAXAGE --http-cache-maxage 2592000 time in SECONDS until cached content expires
PHOTOPRISM_HTTP_CACHE_PUBLIC --http-cache-public allow static content to be cached by a CDN or caching proxy
PHOTOPRISM_HTTP_HOST --http-host Web server IP address
PHOTOPRISM_HTTP_PORT --http-port 2342 Web server port NUMBER
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_CONNS --database-conns 0 maximum NUMBER of open database connections
PHOTOPRISM_DATABASE_CONNS_IDLE --database-conns-idle 0 maximum NUMBER of idle database connections

File Converters

Environment CLI Flag Default Description
PHOTOPRISM_SIPS_BIN --sips-bin sips Sips COMMAND for media file conversion macOS only
PHOTOPRISM_SIPS_BLACKLIST --sips-blacklist avif,avifs do not use Sips to convert files with these EXTENSIONS macOS only
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_BITRATE --ffmpeg-bitrate 50 maximum FFmpeg encoding BITRATE (Mbit/s)
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_DARKTABLE_BIN --darktable-bin darktable-cli Darktable CLI COMMAND for RAW to JPEG conversion
PHOTOPRISM_DARKTABLE_BLACKLIST --darktable-blacklist do not use Darktable to convert files with these EXTENSIONS
PHOTOPRISM_DARKTABLE_CACHE_PATH --darktable-cache-path custom Darktable cache PATH
PHOTOPRISM_DARKTABLE_CONFIG_PATH --darktable-config-path custom Darktable config PATH
PHOTOPRISM_RAWTHERAPEE_BIN --rawtherapee-bin rawtherapee-cli RawTherapee CLI COMMAND for RAW to JPEG conversion
PHOTOPRISM_RAWTHERAPEE_BLACKLIST --rawtherapee-blacklist dng do not use RawTherapee to convert files with these EXTENSIONS
PHOTOPRISM_IMAGEMAGICK_BIN --imagemagick-bin convert ImageMagick CLI COMMAND for image file conversion
PHOTOPRISM_IMAGEMAGICK_BLACKLIST --imagemagick-blacklist heif,heic,heics,avif,avifs,jxl do not use ImageMagick to convert files with these EXTENSIONS
PHOTOPRISM_HEIFCONVERT_BIN --heifconvert-bin heif-convert libheif HEIC image conversion COMMAND
PHOTOPRISM_RSVGCONVERT_BIN --rsvgconvert-bin rsvg-convert librsvg SVG graphics conversion COMMAND pro

Security Tokens

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

Image Quality

Environment CLI Flag Default Description
PHOTOPRISM_THUMB_COLOR --thumb-color sRGB standard color PROFILE for thumbnails (leave blank to disable)
PHOTOPRISM_THUMB_FILTER --thumb-filter lanczos image downscaling filter NAME (best to worst: blackman, lanczos, cubic, linear)
PHOTOPRISM_THUMB_SIZE --thumb-size 2048 maximum size of thumbnails created during indexing in PIXELS (720-7680)
PHOTOPRISM_THUMB_SIZE_UNCACHED --thumb-size-uncached 7680 maximum size of missing thumbnails created on demand in PIXELS (720-7680)
PHOTOPRISM_THUMB_UNCACHED --thumb-uncached enable on-demand creation of missing thumbnails (high memory and cpu usage)
PHOTOPRISM_JPEG_QUALITY --jpeg-quality 85 a higher value increases the QUALITY and file size of JPEG images and thumbnails (25-100)
PHOTOPRISM_JPEG_SIZE --jpeg-size 7680 maximum size of created JPEG sidecar files in PIXELS (720-30000)
PHOTOPRISM_PNG_SIZE --png-size 7680 maximum size of created PNG sidecar files in PIXELS (720-30000)

Face Recognition

To recognize faces, PhotoPrism first extracts crops from your images using a library based on pixel intensity comparisons. These are then fed into TensorFlow to compute 512-dimensional vectors for characterization. In the final step, the DBSCAN algorithm attempts to cluster these so-called face embeddings, so they can be matched to persons with just a few clicks. A reasonable range for the similarity distance between face embeddings is between 0.60 and 0.70, with a higher value being more aggressive and leading to larger clusters with more false positives. To cluster a smaller number of faces, you can reduce the core to 3 or 2 similar faces.

We recommend that only advanced users change these parameters:

Environment CLI Flag Default Description
PHOTOPRISM_FACE_SIZE --face-size 50 minimum size of faces in PIXELS (20-10000)
PHOTOPRISM_FACE_SCORE --face-score 9.000000 minimum face QUALITY score (1-100)
PHOTOPRISM_FACE_OVERLAP --face-overlap 42 face area overlap threshold in PERCENT (1-100)
PHOTOPRISM_FACE_CLUSTER_SIZE --face-cluster-size 80 minimum size of automatically clustered faces in PIXELS (20-10000) essentials
PHOTOPRISM_FACE_CLUSTER_SCORE --face-cluster-score 15 minimum QUALITY score of automatically clustered faces (1-100) essentials
PHOTOPRISM_FACE_CLUSTER_CORE --face-cluster-core 4 NUMBER of faces forming a cluster core (1-100) essentials
PHOTOPRISM_FACE_CLUSTER_DIST --face-cluster-dist 0.640000 similarity DISTANCE of faces forming a cluster core (0.1-1.5) essentials
PHOTOPRISM_FACE_MATCH_DIST --face-match-dist 0.460000 similarity OFFSET for matching faces with existing clusters (0.1-1.5) essentials

Daemon Mode

If you start the server as a daemon in the background, you can additionally specify a filename for the log and the process ID:

Environment CLI Flag Default Description
PHOTOPRISM_PID_FILENAME --pid-filename process id FILE daemon-mode only
PHOTOPRISM_LOG_FILENAME --log-filename server log FILE daemon-mode only

Docker Image

The following variables are used by our Docker images only and have no effect otherwise:

Environment Default Description
PHOTOPRISM_UID 0 run as a non-root user after initialization (supported: 0, 33, 50-99, 500-600, and 900-1200)
PHOTOPRISM_GID 0 run with a specific group id after initialization, to be used together with PHOTOPRISM_UID
PHOTOPRISM_UMASK 0002 file-creation mode (default: u=rwx,g=rwx,o=rx)
PHOTOPRISM_INIT run/install on first startup (options: update gpu tensorflow davfs clitools clean)
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: