Unsplash Wallpaper — GTK4 Wallpaper Manager

UNSPLASH WALLPAPER — GTK4 WALLPAPER MANAGER(7) — A GTK4 + Libadwaita wallpaper manager for Linux that automatically downloads and rotates Unsplash wallpapers with systemd timer scheduling, history, tray integration, and Sway/Wayland support.

($ cd ~/projects && ./sway-unsplash-wallpaper)

NAME

Unsplash Wallpaper — GTK4 Wallpaper Manager — A GTK4 + Libadwaita wallpaper manager for Linux that automatically downloads and rotates Unsplash wallpapers with systemd timer scheduling, history, tray integration, and Sway/Wayland support.

SYNOPSIS

A GTK4 + Libadwaita wallpaper manager for Linux that automatically downloads and rotates Unsplash wallpapers with systemd timer scheduling, history, tray integration, and Sway/Wayland support.

DESCRIPTION

Repository: GitHub - m-elhabib-dev/sway_unsplash_wallpaper

A GTK4 + Libadwaita wallpaper manager for Linux that automatically downloads and rotates Unsplash wallpapers.

The application fetches high-resolution photos from Unsplash and sets them as the desktop wallpaper, with full systemd timer integration for scheduling. It supports 10 curated categories (nature, tech, space, cars, architecture, minimal, mountains, forests, city, gaming) plus custom keyword searches, and tracks download history to avoid duplicate wallpapers.

The GTK4 + Libadwaita UI provides a modern, responsive interface with dark/light/system themes, a system tray via AyatanaAppIndicator, native desktop notifications, multiple resolution options (HD, Full HD, 2K, 4K, original), autostart, a guided first-run wizard, built-in diagnostics, a crash handler, and API key masking in logs.

Native Sway integration uses swaybg, with additional backends for Hyprland, GNOME, KDE Plasma, and other X11 desktops auto-detected at runtime.

TECH STACK

Python GTK4 Libadwaita PyGObject systemd swaybg Unsplash API pytest

ARCHITECTURE

A clean separation between the GUI and scheduling: the GUI manages settings, API keys, categories, history, and manual changes but never schedules; a systemd user timer fires at the configured interval and starts a service that runs --run-job and exits. No internal scheduler, no long-running daemon. Wallpaper backends auto-detected at runtime via WallpaperBackend.detect() (swaybg, hyprctl/hyprpaper, gsettings, qdbus, feh). Settings stored in SQLite.

BUGS / CHALLENGES

Designing a scheduling architecture with no duplicate schedulers — delegating timing entirely to systemd while the GUI stays config-only. Supporting multiple desktop environments through a single auto-detecting backend layer. Masking API keys in logs and handling crashes with desktop notifications. Building a first-run wizard for guided API key setup.

EXIT STATUS / OUTCOMES

Delivered a production-grade Linux desktop application with scheduling, history, and multi-desktop backend support. Automated wallpaper rotation entirely through systemd — no daemon, no internal scheduler. Shipped with tests, diagnostics, release notes, and a contribution workflow.