Config Options¶

Note that changes to the config options listed below always require a restart to take effect.¹ Instead of using environment variables, you can alternatively use an ↪ options.yml file to configure your instance.

Environment Variables¶

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		automatically redirects unauthenticated users to the configured identity provider
PHOTOPRISM_OIDC_REGISTER	--oidc-register		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		allows new OpenID Connect users to use WebDAV when they have a role that allows it
PHOTOPRISM_DISABLE_OIDC	--disable-oidc		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		disables debug mode and only logs startup warnings and errors
PHOTOPRISM_DEBUG	--debug		enables debug mode for development and troubleshooting
PHOTOPRISM_TRACE	--trace		enables 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	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_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` 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		allows uploads that might be offensive (detecting unsafe content requires TensorFlow)
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		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		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		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	Description
PHOTOPRISM_READONLY	--read-only	disables features that require write permission for the originals folder
PHOTOPRISM_EXPERIMENTAL	--experimental	enables new features that may be incomplete or unstable
PHOTOPRISM_DISABLE_FRONTEND	--disable-frontend	disables the web user interface so that only the service API endpoints are accessible
PHOTOPRISM_DISABLE_SETTINGS	--disable-settings	disables the settings frontend and related API endpoints, e.g. in combination with public mode
PHOTOPRISM_DISABLE_BACKUPS	--disable-backups	prevents database and album backups as well as YAML sidecar files from being created
PHOTOPRISM_DISABLE_RESTART	--disable-restart	prevents admins from restarting the server through the user interface
PHOTOPRISM_DISABLE_WEBDAV	--disable-webdav	prevents other apps from accessing PhotoPrism as a shared network drive
PHOTOPRISM_DISABLE_PLACES	--disable-places	disables interactive world maps and reverse geocoding
PHOTOPRISM_DISABLE_TENSORFLOW	--disable-tensorflow	disables face recognition with TensorFlow deprecated
PHOTOPRISM_DISABLE_FACES	--disable-faces	disables face detection and recognition (requires TensorFlow)
PHOTOPRISM_DISABLE_CLASSIFICATION	--disable-classification	disables all image classification and label generation
PHOTOPRISM_DISABLE_FFMPEG	--disable-ffmpeg	disables video transcoding and thumbnail extraction with FFmpeg
PHOTOPRISM_DISABLE_EXIFTOOL	--disable-exiftool	disables metadata extraction with ExifTool (required for full Video, Live Photo, and XMP support)
PHOTOPRISM_DISABLE_VIPS	--disable-vips	disables image processing and conversion with libvips
PHOTOPRISM_DISABLE_SIPS	--disable-sips	disables file conversion using the sips command under macOS
PHOTOPRISM_DISABLE_DARKTABLE	--disable-darktable	disables conversion of RAW images with Darktable
PHOTOPRISM_DISABLE_RAWTHERAPEE	--disable-rawtherapee	disables conversion of RAW images with RawTherapee
PHOTOPRISM_DISABLE_IMAGEMAGICK	--disable-imagemagick	disables conversion of image files with ImageMagick
PHOTOPRISM_DISABLE_HEIFCONVERT	--disable-heifconvert	disables conversion of HEIC images with libheif
PHOTOPRISM_DISABLE_RSVGCONVERT	--disable-rsvgconvert	disables conversion of SVG graphics with librsvg plus
PHOTOPRISM_DISABLE_VECTORS	--disable-vectors	disables vector graphics support plus
PHOTOPRISM_DISABLE_JPEGXL	--disable-jpegxl	disables JPEG XL file format support
PHOTOPRISM_DISABLE_RAW	--disable-raw	disables indexing and conversion of RAW images
PHOTOPRISM_RAW_PRESETS	--raw-presets	enables custom user presets when converting RAW images (reduces performance)
PHOTOPRISM_EXIF_BRUTEFORCE	--exif-bruteforce	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		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

Proxy Server¶

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

Web Server¶

Environment	CLI Flag	Default	Description
PHOTOPRISM_DISABLE_TLS	--disable-tls		disables HTTPS/TLS even if the site URL starts with https:// and a certificate is available
PHOTOPRISM_DEFAULT_TLS	--default-tls		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		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		rule applies to all subdomains as well plus
PHOTOPRISM_STS_PRELOAD	--sts-preload		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_XSS_PROTECTION	--http-xss-protection	1; mode=block	HTTP X-XSS-Protection `HEADER` plus
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		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_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, 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		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		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		flags newly added pictures as private if they might be offensive (requires TensorFlow)

Face Recognition¶

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

We recommend that only advanced users change these parameters:

Environment	CLI Flag	Default	Description
PHOTOPRISM_FACE_ENGINE	--face-engine	auto	face detection engine `NAME` (auto, pigo, 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_ANGLE	--face-angle	-0.3, 0, 0.3	face detection `ANGLE` in radians (repeatable)
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		skips automatic matching of child face embeddings
PHOTOPRISM_FACE_ALLOW_BACKGROUND	--face-allow-background		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

Docker problems? Our troubleshooting guide helps you quickly diagnose and resolve them. 🛟

CLI Reference¶

The following commands can be executed on the host or inside any running container:

photoprism help (or photoprism --help) lists all subcommands and global flags.
photoprism show config (alias photoprism config) displays the current configuration values. Pass --json, --md, --tsv, or --csv to change the output format.
photoprism show config-options displays the supported environment variables with short descriptions and default values.
photoprism show config-yaml displays the YAML configuration keys and their expected types, as well as the corresponding command flags.

View Current Values¶

Before changing environment variables or YAML files, run photoprism config | grep -i <flag> to confirm the current values, such as for password-length:

photoprism config | grep -i password-length

If you are using Docker Compose, you can open a terminal, run docker compose stop, and then run docker compose up -d to restart all services. ↩
Enabling public mode is not recommended for instances installed on a server outside your home network, as this allows others to access your pictures without authentication. ↩