Automate Desktop Wallpaper changing from Unsplash API

Hey there, Darian Vance here. I probably spend more time staring at my monitors than I do sleeping. For a long time, my desktop wallpaper was just… there. Static. After a while, it just becomes background noise. I realized a fresh, high-quality photo every morning is a small thing, but it genuinely helps reset my focus. I built this little Python script to automate it, and it’s one of those 20-minute projects that pays dividends in daily quality-of-life. If you’re busy like me, small, valuable automations are king. Let’s build it.

Prerequisites

• A working Python 3 environment.
• An Unsplash Developer account and an API key (it’s free for this usage level).
• Familiarity with your OS’s task scheduler (Task Scheduler for Windows, cron for macOS/Linux).
• A couple of Python packages which we’ll cover.

The Guide: Step-by-Step

Step 1: Get Your Unsplash API Key

First things first, we need programmatic access to Unsplash’s incredible photo library. Head over to the Unsplash Developers portal and create an account. Once you’re in, create a new application. The process is straightforward; you can name it ‘WallpaperChanger’ or something similar. After creation, you’ll find your API keys in the ‘Keys’ section. The one we need is the ‘Access Key’. Copy that down; we’ll need it in a moment.

Step 2: Project Setup

I’ll skip the standard virtualenv setup since you likely have your own workflow for that. Just make sure you’re working in an isolated project directory. You’ll need two Python packages: `requests` for making HTTP calls to the Unsplash API, and `python-dotenv` for managing our API key securely. In your activated environment, you can install them via pip.

Inside your project folder, create two files: `wallpaper_changer.py` for our script, and a file named `config.env` to store our API key. Do not name it .env, as some systems treat that as a hidden file.

In your `config.env` file, add this one line, pasting your key from Step 1:

UNSPLASH_ACCESS_KEY="your_actual_api_key_here"

Pro Tip: Never, ever commit your `config.env` file or any file with secrets to version control. Add it to your `.gitignore` file immediately. This is a non-negotiable best practice in all my production setups.

Step 3: The Python Script

Alright, let’s get to the core logic. Open `wallpaper_changer.py` and let’s build this out piece by piece.

A. Imports and Configuration

We’ll start by importing the necessary libraries and loading our environment variable. We also define our API endpoint and the path where we’ll save the wallpaper.

import os
import requests
import sys
import ctypes
import subprocess
from dotenv import load_dotenv

# Load environment variables from config.env
load_dotenv('config.env')

# --- Configuration ---
ACCESS_KEY = os.getenv('UNSPLASH_ACCESS_KEY')
API_URL = 'https://api.unsplash.com/photos/random'
# Feel free to change this search query!
SEARCH_QUERY = 'nature landscape'
# We'll save the image in the user's home directory
IMAGE_PATH = os.path.join(os.path.expanduser('~'), 'unsplash_wallpaper.jpg')

B. Fetching and Downloading the Image

Next, let’s create a function to call the Unsplash API. We pass our access key in the headers and our search query as a parameter. If the request is successful, we parse the JSON response to find the URL for the full-resolution image. Then, a second function downloads it.

def get_image_url():
    """Fetches a random image URL from Unsplash."""
    if not ACCESS_KEY:
        print("Error: Unsplash Access Key not found.")
        return None

    headers = {'Authorization': f'Client-ID {ACCESS_KEY}'}
    params = {'query': SEARCH_QUERY, 'orientation': 'landscape'}
    
    try:
        response = requests.get(API_URL, headers=headers, params=params, timeout=10)
        response.raise_for_status()  # Raises an HTTPError for bad responses
        data = response.json()
        return data['urls']['full']
    except requests.exceptions.RequestException as e:
        print(f"Error fetching image from Unsplash: {e}")
        return None

def download_image(url, save_path):
    """Downloads an image from a URL and saves it."""
    if not url:
        print("No URL provided for download.")
        return False
        
    try:
        img_data = requests.get(url, timeout=15).content
        with open(save_path, 'wb') as handler:
            handler.write(img_data)
        print(f"Image saved successfully to {save_path}")
        return True
    except requests.exceptions.RequestException as e:
        print(f"Error downloading image: {e}")
        return False

C. Setting the Wallpaper (OS-Specific)

This is the trickiest part because every operating system does it differently. We’ll use `sys.platform` to detect the OS and run the appropriate command.

def set_wallpaper(image_path):
    """Sets the desktop wallpaper based on the OS."""
    platform = sys.platform
    
    if platform == "win32":
        # For Windows
        try:
            ctypes.windll.user32.SystemParametersInfoW(20, 0, image_path, 3)
            print("Wallpaper set for Windows.")
        except Exception as e:
            print(f"Error setting wallpaper on Windows: {e}")
            
    elif platform == "darwin":
        # For macOS
        try:
            script = f'tell application "Finder" to set desktop picture to POSIX file "{image_path}"'
            subprocess.run(['osascript', '-e', script], check=True)
            print("Wallpaper set for macOS.")
        except (subprocess.CalledProcessError, FileNotFoundError) as e:
            print(f"Error setting wallpaper on macOS: {e}")
            
    elif "linux" in platform:
        # For Linux (GNOME)
        try:
            # This command is for GNOME desktops. Others might need a different command.
            subprocess.run(['gsettings', 'set', 'org.gnome.desktop.background', 'picture-uri', f'file://{image_path}'], check=True)
            print("Wallpaper set for Linux (GNOME).")
        except (subprocess.CalledProcessError, FileNotFoundError) as e:
            print(f"Error setting wallpaper on Linux. Is 'gsettings' available?")
            
    else:
        print(f"Unsupported OS: {platform}")

Pro Tip: The Linux command above is for the GNOME desktop environment. If you use KDE, XFCE, or another environment, you’ll need to find the specific command-line tool for setting the wallpaper. A quick search for “set wallpaper command line [your-desktop-environment]” should get you the right command to substitute.

D. Bringing It All Together

Finally, a `main` function to orchestrate the whole process.

def main():
    """Main function to run the wallpaper changer."""
    print("Starting wallpaper changer script...")
    image_url = get_image_url()
    
    if image_url:
        if download_image(image_url, IMAGE_PATH):
            set_wallpaper(IMAGE_PATH)
    
    print("Script finished.")

if __name__ == "__main__":
    main()

Step 4: Schedule the Automation

A script is only useful if it runs automatically. Here’s how to schedule it.

• On Windows: Use the built-in Task Scheduler. Create a new task, set a trigger (e.g., “Daily” at 8:00 AM), and for the action, point it to your Python executable and provide your `wallpaper_changer.py` script as the argument. Make sure to set the “Start in” field to your project’s directory so it can find the `config.env` file.
• On macOS/Linux: We’ll use cron. You’ll need to edit your crontab. The command you add will look something like this:
  0 8 * * * python3 script.py
  This example runs the script at 8:00 AM every day. A crucial point: cron has a very limited environment. To make this work reliably, you should use the full, absolute path to both your python3 interpreter and your `wallpaper_changer.py` script.

Common Pitfalls

Here’s where I usually mess up when setting this up on a new machine:

• API Rate Limits: Unsplash’s demo rate limit is 50 requests per hour. For a script that runs once a day, this is plenty. But if you’re testing it repeatedly, you might hit the limit. Just wait an hour and you’ll be fine.
• Incorrect Paths in Scheduler: The most common issue. The scheduler (cron or Task Scheduler) can’t find the script or the `config.env` file. Using absolute paths or setting the ‘Start in’ directory (on Windows) is the fix.
• Firewall/Proxy Issues: If you’re on a corporate network, a firewall might block the API calls. You may need to configure the `requests` library to use a proxy.

Conclusion

And that’s it. A simple, effective script that brings a little bit of fresh inspiration to your desktop every day. This is a great “set it and forget it” automation. You can easily customize the `SEARCH_QUERY` variable in the script to match your interests, whether it’s “minimalist architecture,” “space,” or “vintage cars.” Enjoy your new view.

Cheers,
Darian Vance

---

🤖 Frequently Asked Questions