Configuration Reference

The canonical reference for every configuration field. For guidance and examples, see the Configuration guide.

File location

Resolved in order: the --config flag, the WALLPAPER_SERVER_CONFIG environment variable, then ~/.config/wallpaper-server/config.yaml. The file must exist; the server does not create a default.

Fields

YAML key	Type	Default	Description
server.host	string	0.0.0.0	Address to bind
server.port	integer	8519	TCP port
logging.debug	boolean	false	Enable verbose logging
logging.file	string	platform default	Log file path; empty uses the default
wallpaper_folders	list of strings	— (required)	Folders to scan for images
cache_dir	string	~/.cache/wallpaper-server	Cached copies and thumbnails
uploads_dir	string	~/.local/share/wallpaper-server/uploads	Where uploads are stored
supported_extensions	list of strings	.jpg, .jpeg, .png, .webp	Indexed and accepted file types

Notes

• wallpaper_folders is required. With no folders the server exits with no wallpaper folders specified in configuration.
• Paths beginning with ~ are expanded to the user’s home directory.
• cache_dir, uploads_dir and the log directory are created automatically (mode 0755) if they do not exist.
• Default log path on Linux is $XDG_STATE_HOME/wallpaper-server/server.log (falling back to ~/.local/state/…); on macOS it is ~/Library/Logs/wallpaper-server/server.log.

Runtime-editable fields

PUT /api/settings (and the browser settings page) can change server.host, server.port, uploads_dir and wallpaper_folders. cache_dir and supported_extensions are preserved unchanged. Host and port changes require a restart; folder changes require a rescan (POST /api/refresh) or a restart.

CLI flags

Flag	Effect
--start	Start the server (required to run)
--config <path>	Use a specific configuration file
--debug	Enable verbose logging
--autostart	Install and enable a systemd service (uses sudo)
--uninstall-service	Remove the systemd service (uses sudo)
--restart	Restart the systemd service (uses sudo)
--version	Print the version
--help	Print usage