Sway Unsplash Wallpaper - MohamedElhabib Mohamed

SWAY UNSPLASH WALLPAPER(7) — A modern open-source wallpaper manager for Linux desktops that automatically downloads and rotates Unsplash wallpapers. Built with Python, GTK4, and Libadwaita, featuring scheduling, keyword search, wallpaper history, tray integration, and native Sway/Wayland support.

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

NAME

Sway Unsplash Wallpaper — A modern open-source wallpaper manager for Linux desktops that automatically downloads and rotates Unsplash wallpapers. Built with Python, GTK4, and Libadwaita, featuring scheduling, keyword search, wallpaper history, tray integration, and native Sway/Wayland support.

SYNOPSIS

A modern open-source wallpaper manager for Linux desktops that automatically downloads and rotates Unsplash wallpapers. Built with Python, GTK4, and Libadwaita, featuring scheduling, keyword search, wallpaper history, tray integration, and native Sway/Wayland support.

DESCRIPTION

Sway Unsplash Wallpaper is an open-source Linux desktop application that automatically downloads and rotates wallpapers from Unsplash.

The project started from a personal need while using Fedora and Sway. I wanted a lightweight solution that could automatically refresh wallpapers, prevent duplicates, and work seamlessly with Wayland.

The application evolved from a small script into a complete desktop application with a modern user interface, scheduling engine, wallpaper history, diagnostics tools, packaging support, automated testing, and continuous integration.

Key Features

Automatic wallpaper rotation
Custom keyword search
Wallpaper history and duplicate prevention
Native Sway and Wayland support
Tray icon integration
Desktop notifications
Auto-start on login
Diagnostics and troubleshooting tools
Open-source and extensible architecture

TECH STACK

["Python" "GTK4" "Libadwaita" "PyGObject" "SQLite" "Wayland" "Sway" "Systemd" "GitHub Actions" "Pytest" "Ruff" "Unsplash API"]

ARCHITECTURE

The application follows a layered architecture designed for maintainability and future expansion.

Core Layer

Configuration management
SQLite persistence
Data models
Application constants

Service Layer

Unsplash API integration
Wallpaper management
Scheduling engine
History tracking
File storage management

User Interface Layer

GTK4 desktop interface
Libadwaita components
Preferences management
History browser

System Integration Layer

Systemd integration
Tray icon management
Desktop notifications
Wallpaper backend abstraction

The architecture was designed to support future providers and additional desktop environments.

Challenges (Markdown):

BUGS / CHALLENGES

Desktop Development

Most of my previous work focused on web development. Building a Linux desktop application introduced new concepts such as GTK4, Libadwaita, and desktop integration.

Wayland Integration

Managing wallpapers under Wayland and Sway required understanding process management, background services, and desktop-specific behavior.

Packaging and Distribution

Creating a production-ready application involved packaging, dependency management, installation workflows, and release automation.

Reliability

The application includes extensive testing, diagnostics, recovery mechanisms, and error handling to ensure stability during long-running operation.

EXIT STATUS / OUTCOMES

Successfully released as an open-source project on GitHub
Built a complete desktop application from scratch
Implemented 170+ automated tests
Added CI/CD workflows with GitHub Actions
Achieved production-ready architecture and packaging
Gained practical experience in Linux desktop development
Expanded expertise beyond web applications into desktop software engineering

The project transformed a simple personal utility into a fully featured Linux desktop application and provided valuable hands-on experience with application architecture, testing, automation, and open-source development.