FAQ

Can I get a wallpaper with a single request?

Yes. GET /api/wallpapers/random/image returns the image itself, ready to save or set. See retrieving images.

Does Wallpaper Server have authentication?

The image API and gallery are read-only and accessible to reachable clients. Administrative routes require a loopback TCP peer or a bearer token in 2.0.0. A reverse proxy forwarding over loopback must enforce its own authentication. See Security and remote access.

Which image formats are supported?

.jpg, .jpeg, .png and .webp are currently supported. Although supported_extensions exists in configuration, the current service uses a hardcoded allowlist; custom extensions do not yet take effect. See supported formats.

Are there prebuilt binaries?

Verified release tags publish Linux and macOS builds for amd64 and arm64. Source and Docker builds, plus Linux systemd service installation, also work. Check available versions on the Releases page. See installation.

Does deleting a wallpaper remove the file?

External source images are hidden, not removed. Managed uploads move to recoverable trash; only explicit purge permanently removes them. See uploading and managing.

How do I change the wallpaper on a schedule?

Fetch the direct-image endpoint from a scheduled task. See shell and cron and the other automation guides.

How do filters combine?

With AND — every filter must match. An over-constrained query can match nothing. See the filter reference.

Where are cached files and uploads stored?

In XDG-style directories by default (~/.cache/wallpaper-server and ~/.local/share/wallpaper-server/uploads), both configurable. See caching and storage.

Do I need a database?

No. Wallpaper Server is a single binary with an in-memory index and an on-disk cache. See architecture.