Skip to content

Config Options

Changing values in a docker-compose.yml file or in the Advanced Settings UI always requires a restart to take effect. Open a terminal, run docker compose stop, and then run docker compose up -d to restart all services.


PHOTOPRISM_AUTH_MODE: public is NOT recommended for instances installed on a server accessible from outside your home network.

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, must have at least 8 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)


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


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) sponsors only
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_USERS_PATH --users-path custom users storage 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_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_WEBDAV --disable-webdav disable built-in WebDAV server
PHOTOPRISM_DISABLE_SETTINGS --disable-settings disable settings UI and API
PHOTOPRISM_DISABLE_PLACES --disable-places disable reverse geocoding and maps
PHOTOPRISM_DISABLE_BACKUPS --disable-backups disable backing up albums and photo metadata to YAML files
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_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_HEIFCONVERT --disable-heifconvert disable conversion of HEIC/HEIF files
PHOTOPRISM_DISABLE_DARKTABLE --disable-darktable disable conversion of RAW files with Darktable
PHOTOPRISM_DISABLE_RAWTHERAPEE --disable-rawtherapee disable conversion of RAW files with RawTherapee
PHOTOPRISM_DISABLE_SIPS --disable-sips disable conversion of RAW files with Sips macOS only
PHOTOPRISM_DISABLE_RAW --disable-raw disable indexing and conversion of RAW files
PHOTOPRISM_RAW_PRESETS --raw-presets enables applying user presets when converting RAW files (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)


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 sponsors only
PHOTOPRISM_APP_MODE --app-mode standalone progressive web app MODE (fullscreen, standalone, minimal-ui, browser)
PHOTOPRISM_APP_ICON --app-icon progressive web app ICON (logo, app, crisp, mint, bold) sponsors only
PHOTOPRISM_APP_NAME --app-name progressive web app NAME when installed on a device sponsors only
PHOTOPRISM_LEGAL_INFO --legal-info legal information TEXT, displayed in the page footer sponsors only
PHOTOPRISM_LEGAL_URL --legal-url legal information URL sponsors only
PHOTOPRISM_WALLPAPER_URI --wallpaper-uri login screen background image URI sponsors only

Site Information

Environment CLI Flag Default Description
PHOTOPRISM_CDN_URL --cdn-url content delivery network URL sponsors only
PHOTOPRISM_SITE_URL --site-url public site URL
PHOTOPRISM_SITE_AUTHOR --site-author site OWNER, copyright, or artist
PHOTOPRISM_SITE_TITLE --site-title site TITLE sponsors only
PHOTOPRISM_SITE_CAPTION --site-caption AI-Powered Photos App site CAPTION
PHOTOPRISM_SITE_DESCRIPTION --site-description site DESCRIPTION optional
PHOTOPRISM_SITE_PREVIEW --site-preview sharing preview image URL sponsors only

Web Server

Environment CLI Flag Default Description
PHOTOPRISM_TRUSTED_PROXY --trusted-proxy CIDR range from which reverse proxy headers can be trusted
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_HTTP_MODE --http-mode Web server MODE (debug, release, or test)
PHOTOPRISM_HTTP_COMPRESSION --http-compression Web server compression METHOD (none or gzip)
PHOTOPRISM_HTTP_HOST --http-host Web server IP address
PHOTOPRISM_HTTP_PORT --http-port 2342 Web server port NUMBER
PHOTOPRISM_DISABLE_TLS --disable-tls disable HTTPS even if a certificate is available

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_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_SIPS_BIN --sips-bin sips Sips COMMAND for RAW to JPEG conversion macOS only
PHOTOPRISM_SIPS_BLACKLIST --sips-blacklist avif,avifs do not use Sips to convert files with these EXTENSIONS macOS only
PHOTOPRISM_HEIFCONVERT_BIN --heifconvert-bin heif-convert HEIC/HEIF/AVIF image conversion COMMAND
PHOTOPRISM_FFMPEG_BIN --ffmpeg-bin ffmpeg FFmpeg COMMAND for video transcoding and thumbnail extraction
PHOTOPRISM_FFMPEG_ENCODER --ffmpeg-encoder libx264 FFmpeg AVC encoder NAME sponsors only
PHOTOPRISM_FFMPEG_BITRATE --ffmpeg-bitrate 50 maximum FFmpeg encoding BITRATE (Mbit/s)
PHOTOPRISM_EXIFTOOL_BIN --exiftool-bin exiftool ExifTool COMMAND for extracting metadata

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)

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) sponsors only
PHOTOPRISM_FACE_CLUSTER_SCORE --face-cluster-score 15 minimum QUALITY score of automatically clustered faces (1-100) sponsors only
PHOTOPRISM_FACE_CLUSTER_CORE --face-cluster-core 4 NUMBER of faces forming a cluster core (1-100) sponsors only
PHOTOPRISM_FACE_CLUSTER_DIST --face-cluster-dist 0.640000 similarity DISTANCE of faces forming a cluster core (0.1-1.5) sponsors only
PHOTOPRISM_FACE_MATCH_DIST --face-match-dist 0.460000 similarity OFFSET for matching faces with existing clusters (0.1-1.5) sponsors only

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 https gpu tensorflow davfs clitools clean)
PHOTOPRISM_DISABLE_CHOWN false disable updating storage permissions via chmod and chown on startup

Some options, such as those for hardware transcoding, are only available to sponsors due to the time required for testing, maintenance, and providing support.