Linux Wallpaper Switcher

Linux is great but unlike windows, it does not have an inbuilt functionality of switching desktop background at specific time interval. Therefore here is a simple Python script to automatically change your desktop wallpaper on GNOME-based Linux distributions at a specified interval.

Features

• Random Wallpaper Selection: Chooses a random image from a specified directory.
• Easy Configuration: All settings are managed in a simple config.py file.
• Recursive Search: Can optionally search for images in subdirectories.
• Interval-based Switching: Automatically changes the wallpaper after a user-defined period.
• Easy Installation: An install.sh script is provided to set up the systemd service automatically.
• Image Caching: Intelligent caching system that tracks directory changes for improved performance.
• Error Recovery: Exponential backoff retry mechanism for resilient wallpaper setting.
• Test Mode: Built-in diagnostic tool to verify configuration and gsettings availability.
• Service Management: Control the service directly from the script (start, stop, restart, enable, disable).
• Proper Logging: Structured logging for better debugging and service monitoring.

Requirements

• Python 3.x
• A GNOME-based desktop environment (e.g., Ubuntu, Fedora Workstation, Debian with GNOME) for gsettings to work.

Installation and Setup

1. Clone the repository (or download the script):

   git clone https://github.com/ShivayeModi/switch-linux-wallpaper.git
   cd switch-linux-wallpaper

2. Configure the script: Open the config.py file and edit the following values:

   • WALLPAPER_DIR: The absolute path to the directory containing your wallpapers (e.g., "/home/user/Pictures/Wallpapers").
   • TIME_INTERVAL: The time in seconds between wallpaper changes (e.g., 300 for 5 minutes).
   • IS_RECURSIVE: Set to True to search for images in subdirectories, or False to only search the main directory.
   • VALID_EXTENSIONS: The set of file extensions to consider as images.

3. Run the installation script: This will set up and start the systemd service for you.

   ./install.sh

The wallpaper switcher is now installed and running. It will automatically start on login.

Manual Usage

If you do not wish to use the systemd service, you can run the script manually from your terminal. All configuration is handled by config.py.

python3 wallpaper_switcher.py

Command-Line Options

• Daemon mode (default):

  python3 wallpaper_switcher.py

  Runs the wallpaper switcher continuously in the foreground.

• Test mode:

  python3 wallpaper_switcher.py --test

  Validates configuration, checks directory and images, verifies gsettings availability, and tests setting a wallpaper. Useful for diagnosing issues.

• Service management:

  python3 wallpaper_switcher.py start      # Start the service
  python3 wallpaper_switcher.py stop       # Stop the service
  python3 wallpaper_switcher.py restart    # Restart the service
  python3 wallpaper_switcher.py status     # Check service status
  python3 wallpaper_switcher.py enable     # Enable service on login
  python3 wallpaper_switcher.py disable    # Disable service on login

Troubleshooting

• "Error: 'gsettings' command not found...": This script is designed for GNOME-based desktop environments. If you are using a different desktop, you may need to modify the set_wallpaper function to use the appropriate command for your environment.

• "Error: Directory not found...": Ensure the WALLPAPER_DIR in config.py points to a valid and accessible directory.

• "No images found...": Check that the specified directory contains valid image files and that IS_RECURSIVE in config.py is set correctly for your folder structure.

• Service not starting/working:

  • Check the service status: systemctl --user status wallpaper-switcher.service
  • View logs for errors: journalctl --user -u wallpaper-switcher.service -f
  • Run test mode to diagnose issues: python3 wallpaper_switcher.py --test

• Cache issues: If you suspect the image cache is corrupted or stale, it's located at ~/.cache/wallpaper-switcher/image_cache.json. You can safely delete it to force a directory rescan.

• Wallpaper not changing:

  • Verify your wallpaper directory has images with supported extensions (.jpg, .jpeg, .png, .bmp)
  • Check TIME_INTERVAL in config.py is not set too high
  • Run test mode to verify gsettings is working: python3 wallpaper_switcher.py --test

---