Caching and Storage

Wallpaper Server keeps your original images where they are and maintains a separate on-disk cache for fast serving.

What is stored where

Location	Default	Contents
Source folders	your wallpaper_folders	Your original images — never modified.
Cache directory	~/.cache/wallpaper-server	Cached copies and thumbnails.
Uploads directory	~/.local/share/wallpaper-server/uploads	Images added via the API or gallery.

These paths are configurable (configuration reference) and follow XDG conventions. ~ is expanded, and the directories are created automatically (mode 0755) if missing.

The cache

• Cached copies: each source image is copied into the cache directory. The copy is reused unless the source file is newer (compared by modification time), in which case it is regenerated.
• Thumbnails: stored under thumbnails/ in the cache directory as JPEGs (max 300×200), regenerated when the source is newer.

The cache is rebuilt by POST /api/refresh, which rescans folders and swaps in a freshly built index atomically — the server never serves from an empty or half-built index during a refresh.

Note

There is no automatic cache eviction and the cache is not size-bounded. It grows with your library. Deleting the cache directory’s contents is safe: entries are regenerated on demand or on the next refresh.

Uploads

Uploaded images are written to the uploads directory with a generated filename, then analysed and indexed immediately. They become first-class wallpapers, indistinguishable from images in your source folders.

Danger

Deleting a wallpaper through the API or gallery removes the original file — whether it came from a source folder or an upload — along with its cached copy and thumbnail. See Uploading and managing.

Related

• Configuration reference
• Troubleshooting