photoprism/internal/config/README.md

PhotoPrism — Config Package

Last Updated: February 14, 2026

Overview

PhotoPrism’s runtime configuration is managed by this package. Fields are defined in options.go and then initialized with values from command-line flags, environment variables, and optional YAML files (storage/config/*.yml).

Client config values are derived from the runtime configuration and exposed to the frontend via GET /api/v1/config. This includes a storageNamespace value (SHA-256 hash of SiteUrl) used by the browser to scope local storage keys on shared domains.

Storage Namespace & Legacy Session Compatibility

• storageNamespace is deterministic per SiteUrl (SHA-256(SiteUrl)) and is used by the frontend storage wrappers to isolate data on shared domains.
• Frontend reads from namespaced keys first and then falls back to legacy global keys; when a legacy value is found, it is migrated to the active namespace on read.
• Legacy mobile/webview integrations should prefer writing both global session.token and session.id when pre-populating authentication data.
• Writing only a token is not enough to restore an authenticated user session in current frontend logic, because session restore requires both token and session id.
• Older compatibility keys (authToken / sessionId) are only auto-migrated when both are present.

Sources & Precedence

PhotoPrism loads configuration in the following order:

1. Built-in defaults defined in this package.
2. defaults.yml — optional configuration defaults. PhotoPrism first checks /etc/photoprism/defaults.yml (or .yaml). If that file is missing or empty, it automatically falls back to storage/config/defaults.yml (respecting .yml / .yaml as well) under PHOTOPRISM_CONFIG_PATH. See defaults.yml if you package PhotoPrism for other environments and need to override the compiled defaults.
3. Environment variables prefixed with PHOTOPRISM_… and specified in flags.go along with the CLI flags. This is the primary override mechanism in container environments.
4. options.yml — user-level configuration stored under storage/config/options.yml (or another directory controlled by PHOTOPRISM_CONFIG_PATH). Values here override both defaults and environment variables, see options.yml.
5. CLI flags (for example photoprism --cache-path=/tmp/cache). Flags always win when a conflict exists.

The PHOTOPRISM_CONFIG_PATH variable controls where PhotoPrism looks for YAML files (defaults to storage/config).

Any change to configuration (flags, env vars, YAML files) requires a restart. The Go process reads options during startup and does not watch for changes.

Inspect Before Editing

Before changing environment variables or YAML files, run photoprism config | grep -i <flag> to confirm the current value of a flag, such as site-url, or site to show all related values:

photoprism config | grep -i site

Example output:

Name	Value
site-url	https://app.localssl.dev/
site-https	true
site-domain	app.localssl.dev
site-author	@photoprism_app
site-title	PhotoPrism

CLI Reference

• photoprism help (or photoprism --help) lists all subcommands and global flags.
• photoprism show config (alias photoprism config) renders every active option along with its current value. Pass --json, --md, --tsv, or --csv to change the output format.
• photoprism show config-options prints the description and default value for each option. Use this when updating flags.go.
• photoprism show config-yaml displays the configuration keys and their expected types in the same structure that the YAML files use. It is a read-only helper meant to guide you when editing files under storage/config.
• Additional show subcommands document search filters, metadata tags, and supported thumbnail sizes; see internal/commands/show.go for the complete list.