Plasma APOD Wallpaper

A Plasma 6 wallpaper that displays NASA's Astronomy Picture of the Day (APOD). It supports still images and looping videos. The command-line tool downloads the daily media, and the wallpaper reads the downloaded files from a local cache.

Requirements

• KDE Plasma 6
• Python 3.13 or newer
• uv
• ffmpeg and ffprobe from an FFmpeg package
• systemctl with an active user systemd session
• kpackagetool6 from KDE Plasma 6

The computer must have network access to science.nasa.gov to fetch APOD media.

Install

Install the CLI with uv, then use the CLI to install the wallpaper and its scheduled fetch service:

uv tool install plasma-apod-wallpaper
plasma-apod-wallpaper install

If the CLI is already installed, upgrade it before running setup:

uv tool upgrade plasma-apod-wallpaper
plasma-apod-wallpaper install

The install command installs the Plasma wallpaper package, creates a user systemd service and timer, and writes the QML environment setting. The timer starts at 04:05 UTC and retries hourly afterward. The fetcher uses NASA's APOD WordPress API with its public DEMO_KEY; a current manifest avoids repeat API requests after a successful fetch.

Log out and back in, or restart Plasma, to apply the QML environment setting. Then run systemsettings, open Wallpaper, and select APOD Wallpaper.

Use

The timer fetches APOD automatically. To fetch it immediately, run:

plasma-apod-wallpaper fetch

Running the command without a subcommand also fetches APOD:

plasma-apod-wallpaper

The Plasma wallpaper reads the manifest and media files from ~/.cache/plasma-apod-wallpaper. Multiple images are displayed in a rotating slideshow; videos loop as the wallpaper. The cache remains on disk after uninstall.

Image URLs come from the API's basic_html, including both images on rollover days; a matching hdurl upgrades the matching image. Video entries use the direct video source in basic_html, not the hdurl snapshot.

Fetch warnings and errors are appended to ~/.cache/plasma-apod-wallpaper/fetch.log.gz. The log is gzip-compressed. A successful fetch adds one summary line.

Older installs may have data in ~/.cache/apodvideo. The new cache does not import that data; run plasma-apod-wallpaper cleanup-legacy to remove it.

Uninstall

Remove the Plasma provider and disable its timer with:

plasma-apod-wallpaper uninstall

By default, uninstall keeps the cache and setup files. Add --delete-cache to delete the current and old cache directories. Add --delete-settings to remove the user service, timer, and QML environment setting. You can use both options:

plasma-apod-wallpaper uninstall --delete-cache --delete-settings

To remove the old ~/.cache/apodvideo cache and leftover setup settings without removing the current wallpaper provider or cache, run:

plasma-apod-wallpaper cleanup-legacy

This cleanup disables scheduled fetching. If you want to keep using the wallpaper, run plasma-apod-wallpaper install again to restore its service and environment setting. uninstall and cleanup-legacy leave the CLI installed. To also remove the CLI, run:

uv tool uninstall plasma-apod-wallpaper

Log out and back in, or restart Plasma, to remove the environment setting from the running session.

Help and troubleshooting

Show the available commands and examples:

plasma-apod-wallpaper --help
plasma-apod-wallpaper fetch --help

Check the timer and recent fetch logs with systemd:

systemctl --user status plasma-apod-wallpaper.timer
systemctl --user list-timers plasma-apod-wallpaper.timer
journalctl --user -u plasma-apod-wallpaper.service

Read the compressed fetch log with:

gzip -dc ~/.cache/plasma-apod-wallpaper/fetch.log.gz

If install reports missing tools, install FFmpeg and KDE Plasma 6 package tools, then run plasma-apod-wallpaper install again. If the wallpaper does not appear in System Settings, restart Plasma, run systemsettings, and check the Wallpaper selector again.