Skip to content
Wallpaper Server Wallpaper Server Docs

Configuration

Wallpaper Server is configured with a single YAML file. This page explains what each setting does; the Configuration Reference lists every field, type and default in one table.

Where configuration is loaded from

Section titled “Where configuration is loaded from”

At startup the server resolves its configuration file in this order:

  1. The path passed to the --config flag.
  2. The WALLPAPER_SERVER_CONFIG environment variable.
  3. The default: ~/.config/wallpaper-server/config.yaml.

If the resolved file does not exist, the server exits with Configuration file not found. There is no auto-generated default file — you must create one.

Minimal configuration

Section titled “Minimal configuration”

The smallest working configuration sets a server address and one wallpaper folder:

config.yaml
server:
  host: 0.0.0.0
  port: 8519
wallpaper_folders:
  - /home/you/Pictures/Wallpapers

Full configuration

Section titled “Full configuration”

Every other field has a sensible default and can be omitted. A complete example:

config.yaml
server:
  host: 0.0.0.0
  port: 8519


logging:
  debug: false
  file: ""            # empty uses the platform default log path


wallpaper_folders:
  - /home/you/Pictures/Wallpapers
  - /mnt/media/wallpapers


cache_dir: ~/.cache/wallpaper-server
uploads_dir: ~/.local/share/wallpaper-server/uploads


supported_extensions:
  - .jpg
  - .jpeg
  - .png
  - .webp

Settings explained

Section titled “Settings explained”

Server

Section titled “Server”
  • server.host — the address to bind. Defaults to 0.0.0.0, which listens on all interfaces. Use 127.0.0.1 to restrict access to the local machine.
  • server.port — the TCP port. Defaults to 8519.

Wallpaper folders

Section titled “Wallpaper folders”

wallpaper_folders is a list of directories to scan. Every supported image found in these folders (recursively) is analysed and added to the index. Unreadable sub-entries are skipped with a warning; an unreadable top-level folder is a fatal error.

Cache and uploads

Section titled “Cache and uploads”
  • cache_dir — where cached copies and thumbnails are written. Defaults to ~/.cache/wallpaper-server. Created automatically if missing.
  • uploads_dir — where images uploaded through the API or gallery are stored. Defaults to ~/.local/share/wallpaper-server/uploads.

Paths beginning with ~ are expanded to your home directory. These follow the XDG base-directory convention. See Caching and storage for details.

Supported extensions

Section titled “Supported extensions”

supported_extensions controls which file types are indexed and accepted for upload. Defaults to .jpg, .jpeg, .png and .webp. See Supported formats.

Logging

Section titled “Logging”
  • logging.debug — enable verbose logging (equivalent to the --debug flag).
  • logging.file — path to a log file. When empty, a platform default is used (for example ~/.local/state/wallpaper-server/server.log on Linux).

Changing configuration at runtime

Section titled “Changing configuration at runtime”

Some settings can be changed through the browser settings page or the PUT /api/settings endpoint: server.host, server.port, uploads_dir and wallpaper_folders. Updating settings writes them back to the configuration file.