ICON: Swapping Desktop Shortcut Icons for SteamGridDB Art

Game shortcuts on a Windows desktop tend to look like a yard sale. Some have a crisp icon, some have a blurry 32-pixel thing the installer shipped, and every one of them has that little shortcut arrow in the corner. If you've already made your Steam library look nice, the desktop starts to feel like the room you didn't clean.

desktop-icon-grid (the app itself is called ICON) fixes that. It came out of Vapor, my Steam library artwork manager, and borrows the same idea: let SteamGridDB supply the art and let a script do the clicking.

What it does

ICON scans your desktop for shortcuts, cleans up their names, searches SteamGridDB for matching square grid artwork, and swaps the icon over. You get 1:1 art at 512 or 1024 pixels instead of whatever the installer left behind.

Feature	What it means
Desktop scanning	Finds shortcuts, .exe files and .url links on Windows, .desktop files on Linux
Name cleanup	Strips "- Shortcut", stray numbers and other junk before searching
Backup and restore	Saves the original icon paths to a timestamped JSON file before changing anything
Selective or auto	Pick icons one by one, or apply everything with --auto
Overlay removal	Hides the shortcut arrow and UAC shield on Windows
Async downloads	Fetches in parallel, with caching and retries to stay kind to the API

How it works

The pipeline is six steps. Scan the desktop. Clean the names. Search SteamGridDB for a match. Download the highest-rated square grid image. Convert it to a multi-resolution .ico (or PNG on Linux). Point the shortcut at the new icon.

Only real shortcut files can be changed. A .lnk or .desktop file just points at an icon, so swapping it is easy. An .exe carries its icon inside the binary, and changing that means rebuilding the program, so ICON leaves executables alone.

Heads up

SteamGridDB is mostly a games database. Your game shortcuts will match well, but your text editor or password manager may come back empty. Renaming a shortcut to the exact game or app name often helps.

Version 2.0 moved everything over to aiohttp for concurrent downloads, added Linux support, a pytest suite and CI on GitHub Actions, and the --restore option.

Using it

On Windows there's a standalone ICON.exe in the releases, and you start it through ICON_Launcher.bat to get the menu. Double-clicking the .exe on its own just flashes a console window and closes, since it's a command-line tool.

From Python it's:

pip install -r requirements.txt
python icon_replacer.py --setup
python icon_replacer.py

The setup wizard asks for your free SteamGridDB API key and saves your settings. After that, a few flags cover most of what you'll want:

python icon_replacer.py --list
python icon_replacer.py --auto
python icon_replacer.py --restore latest
python icon_replacer.py --remove-overlays

Tip

Run --list first. It shows what's on your desktop without touching anything, which is a good way to see how the name matching will go.

Rough edges

A few honest caveats:

• Overlay removal edits the registry. It needs admin rights, drops a blank.ico into your Documents folder, and restarts Explorer. Delete that file and the arrows come back. --restore-overlays undoes it.
• .url internet shortcuts only get limited support.
• Windows caches icons aggressively. If the new art doesn't show up, refresh the desktop or restart Explorer.
• Rate limits. If you hit SteamGridDB's limits, wait a few minutes and try again.

If you want the same art in Steam itself, that's Vapor's job, and Deckport uses SteamGridDB for native games on the Steam Deck.

Try it

It's MIT licensed and on GitHub. Run --list, then try it on a handful of game shortcuts before you let --auto loose on the whole desktop.