Config Options

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_LOGIN_INFO	–login-info		custom login footer info TEXT plus
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_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_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_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_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)

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 plus
PHOTOPRISM_DISABLE_VECTORS	–disable-vectors	false	disables vector graphics support plus
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_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)
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, copyright, or artist
PHOTOPRISM_SITE_TITLE	–site-title		site TITLE
PHOTOPRISM_SITE_CAPTION	–site-caption	AI-Powered Photos App	site CAPTION
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	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_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_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
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) plus
PHOTOPRISM_STS_SUBDOMAINS	–sts-subdomains	false	rule applies to all subdomains as well plus
PHOTOPRISM_STS_PRELOAD	–sts-preload	false	submit to Google’s HSTS preload service plus
PHOTOPRISM_AUTH_LIMIT	–auth-limit	60	maximum number of consecutive invalid access TOKENS from a single IP plus
PHOTOPRISM_AUTH_INTERVAL	–auth-interval	10s	average DURATION between invalid access tokens from a single IP (0-86400s) plus
PHOTOPRISM_LOGIN_LIMIT	–login-limit	10	maximum number of consecutive failed LOGINS from a single IP plus
PHOTOPRISM_LOGIN_INTERVAL	–login-interval	1m0s	average DURATION between failed logins from a single IP (0-86400s) plus
PHOTOPRISM_IPS_LIMIT	–ips-limit	3	maximum number of malicious request ATTEMPTS before a client IP is blocked (-1 to disable) plus
PHOTOPRISM_IPS_INTERVAL	–ips-interval	1h0m0s	average DURATION between malicious request attempts from a single IP (0-86400s) plus
PHOTOPRISM_HTTP_CSP	–http-csp		HTTP Content-Security-Policy (CSP) HEADER plus
PHOTOPRISM_HTTP_CTO	–http-cto	nosniff	HTTP X-Content-Type-Options HEADER plus
PHOTOPRISM_HTTP_COOP	–http-coop	same-origin	HTTP Cross-Origin-Opener-Policy (COOP) HEADER plus
PHOTOPRISM_HTTP_REFERRER_POLICY	–http-referrer-policy	same-origin	HTTP Referrer-Policy HEADER plus
PHOTOPRISM_HTTP_FRAME_OPTIONS	–http-frame-options	DENY	HTTP X-Frame-Options HEADER plus
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 plus

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 plus
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

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:

• PhotoPrism® User Guide
• PhotoPrism® Setup Guide
• PhotoPrism® Config Files
• PhotoPrism® Knowledge Base