Skip to content
/ APP-ICON-Desktop-Icon-Grid-Replacer Public

[100% Complete] Desktop icon replacer using SteamGridDB artwork. Cross-platform (Windows/Linux) with backup/restore, async downloads, and overlay removal.

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

wesellis/APP-ICON-Desktop-Icon-Grid-Replacer

BranchesTags

Repository files navigation

ICON - Desktop Icon Grid Replacer

A tool to replace desktop icons with 1:1 grid artwork from SteamGridDB.

Python License Platform Tests Coverage Stars Last Commit

ICON scans your Windows or Linux desktop for shortcuts, searches for matching artwork on SteamGridDB, and replaces the icons with 512x512 or 1024x1024 square grid images.

What's New in v2.0

  • Linux Support - Cross-platform compatibility for both Windows and Linux
  • Async Architecture - Concurrent downloads using aiohttp
  • Test Coverage - 80%+ code coverage with pytest
  • Backup/Restore - Restore icons from any backup with --restore
  • Modern Packaging - pip installation with setup.py and pyproject.toml
  • CI/CD - Automated testing with GitHub Actions
  • Error Handling - Informative error messages and recovery

Features

  • Automatic Desktop Scanning - Finds all shortcuts on your desktop (Windows & Linux)
  • High-Quality Icons - Downloads 512x512 or 1024x1024 square grid artwork
  • Smart Matching - Cleans up names for better search results
  • Backup & Restore - Automatically backs up original icons and restore anytime
  • Async Downloads - Concurrent downloads with caching and connection pooling
  • Selective Application - Choose which icons to replace (or auto-apply all)
  • Overlay Removal - Optional removal of UAC shields and shortcut arrows (Windows)
  • Cross-Platform - Works on both Windows (.lnk) and Linux (.desktop)

Installation

Windows Standalone (Easiest - No Python Required)

  1. Download ICON.exe and ICON_Launcher.bat from Releases
  2. Double-click ICON_Launcher.bat to launch the interactive menu
  3. Choose option 1 to run setup wizard
  4. Get API Key from https://www.steamgriddb.com/profile/preferences/api and paste it
  5. Use the menu to replace icons, restore backups, or remove overlays

The standalone .exe includes all dependencies and works on Windows 10+.

Note: If you double-click ICON.exe directly, it will open and close immediately because it's a command-line tool. Use ICON_Launcher.bat for the interactive menu, or run from Command Prompt with options like ICON.exe --help.

Python Installation (Cross-Platform)

Prerequisites:

Quick Install (Recommended):

# Clone the repository
git clone https://github.com/wesellis/APP-ICON-Desktop-Icon-Grid-Replacer.git
cd APP-ICON-Desktop-Icon-Grid-Replacer

# Install with pip (includes all dependencies)
pip install -e .

# Or install for development (includes test tools)
pip install -e ".[dev]"

Manual Install (Python)

  1. Clone or download this repository:
git clone https://github.com/wesellis/icon-replacer.git
cd icon-replacer
  1. Install dependencies:
pip install -r requirements.txt
  1. Run the setup wizard:
python icon_replacer.py --setup

Usage

Quick Start

# Run with interactive mode (choose which icons to replace)
python icon_replacer.py

# Auto-apply all icons without confirmation
python icon_replacer.py --auto

# Just list what's on your desktop
python icon_replacer.py --list

Command-Line Options

python icon_replacer.py [OPTIONS]

Options:
  --setup                Run interactive setup wizard
  --list                 List desktop items without making changes
  --restore BACKUP       Restore icons from backup (use 'latest' for most recent)
  --remove-overlays      Remove UAC shields and shortcut arrows (Windows only)
  --restore-overlays     Restore default UAC/shortcut overlays (Windows only)
  --api-key KEY          SteamGridDB API key
  --size SIZE            Icon size: 512 or 1024 (default: 1024)
  --desktop-path PATH    Custom desktop path (default: ~/Desktop)
  --auto                 Auto-apply without confirmation
  --no-backup            Skip backup creation
  --verbose, -v          Verbose output

Examples

# Use specific API key and icon size
python icon_replacer.py --api-key YOUR_KEY --size 512

# Custom desktop path
python icon_replacer.py --desktop-path "C:\Users\YourName\Desktop"

# Auto mode with no backup (use with caution!)
python icon_replacer.py --auto --no-backup

# Restore from latest backup
python icon_replacer.py --restore latest

# Restore from specific backup
python icon_replacer.py --restore backup_20231201_143022.json

# Remove UAC shields and shortcut arrows (Windows)
python icon_replacer.py --remove-overlays

# Restore default overlays (Windows)
python icon_replacer.py --restore-overlays

Overlay Removal Feature

ICON includes a feature to remove the UAC shield and shortcut arrow overlays from your desktop icons:

What it removes:

  • UAC shield overlays (on administrator shortcuts)
  • Shortcut arrow overlays (on all shortcuts)

How to use:

# During setup wizard
python icon_replacer.py --setup
# Answer "yes" when prompted about overlay removal

# Or run separately
python icon_replacer.py --remove-overlays

Important notes:

  • Requires administrator privileges to modify registry
  • Places a blank.ico file in your Documents folder
  • Do NOT delete blank.ico or overlays will reappear
  • Can be restored anytime with --restore-overlays

How it works:

  • Copies a blank icon file to Documents folder
  • Modifies Windows registry to use blank icon for overlays
  • Restarts Windows Explorer to apply changes

## How It Works

1. **Scans Desktop** - Finds all `.lnk` shortcuts, `.exe` files, and `.url` links
2. **Cleans Names** - Removes "- Shortcut", numbers, and other junk from names
3. **Searches SteamGridDB** - Looks for matching games/apps with square grid artwork
4. **Downloads Icons** - Gets the highest-rated 1:1 grid artwork
5. **Converts Format** - Converts to Windows `.ico` format with multiple resolutions
6. **Updates Shortcuts** - Changes the icon path in the Windows shortcut

## Configuration

After running `--setup`, your configuration is saved to:

~/.icon_replacer/config.json


Configuration includes:
- SteamGridDB API key
- Preferred icon size (512 or 1024)
- Auto-backup preference
- Icons directory path

## File Locations

~/.icon_replacer/ ├── config.json # Your configuration ├── icons/ # Downloaded and converted icons ├── backups/ # Backup files (JSON) └── icon_replacer.log # Application log


## Backup & Restore

ICON automatically creates backups before making changes. Backups are stored as JSON files with timestamps:

~/.icon_replacer/backups/backup_20231201_143022.json


To restore from a backup, you can manually edit the shortcuts or use the backup file to reference original icon paths.

## Supported File Types

### Windows
- ✅ `.lnk` - Windows shortcuts (fully supported)
- ⚠️ `.exe` - Executables (read-only, cannot change embedded icons)
- ⚠️ `.url` - Internet shortcuts (limited support)

### Linux
- ✅ `.desktop` - Desktop entry files (fully supported)

**Note**: Only shortcut files (`.lnk` on Windows, `.desktop` on Linux) can have their icons replaced. Executables have embedded icons that cannot be changed without recompiling.

## Troubleshooting

### "No icon found on SteamGridDB"
- The app name might not match anything in the database
- Try renaming the shortcut to match the game/app name exactly
- Not all apps are in SteamGridDB (it's primarily for games)

### "Failed to update icon"
- Ensure you have write permissions to the desktop
- The shortcut file might be in use or locked
- Try running as administrator

### Icons not appearing after update
- Refresh your desktop (F5)
- Restart Windows Explorer (Ctrl+Shift+Esc → File → Restart Explorer)
- Windows icon cache might need clearing

### Clear Windows Icon Cache
```cmd
ie4uinit.exe -show
ie4uinit.exe -ClearIconCache

API Rate Limits

SteamGridDB has rate limits on their API. ICON uses:

  • Caching - Reduces duplicate API calls
  • Connection pooling - Reuses connections efficiently
  • Retry logic - Handles temporary failures gracefully

If you hit rate limits, wait a few minutes before trying again.

Project Structure

APP-ICON-Desktop-Icon-Grid-Replacer/
├── icon_replacer.py          # Main application
├── requirements.txt          # Python dependencies
├── README.md                 # This file
├── src/
│   ├── steamgrid_api.py     # SteamGridDB API integration
│   ├── desktop_scanner.py    # Desktop scanning logic
│   └── icon_updater.py       # Icon download and update logic
├── assets/                   # Screenshots and media
├── config/                   # Configuration templates
└── docs/                     # Additional documentation

Development

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_steamgrid_api.py

# Run with verbose output
pytest -v

Code Quality

# Format code with black
black .

# Sort imports with isort
isort .

# Lint with flake8
flake8 src/

# Type check with mypy
mypy src/

# Security scan with bandit
bandit -r src/

Contributing

Contributions welcome! Please feel free to submit issues or pull requests.

How to Contribute

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (pytest)
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

Code Standards

  • Follow PEP 8 style guidelines
  • Use black for code formatting
  • Write tests for new features
  • Update documentation as needed
  • Ensure all tests pass before submitting PR

Related Projects

  • VAPOR - Steam Grid Artwork Manager (the inspiration for this tool)

License

MIT License - see LICENSE file for details

Credits

Disclaimer

This tool modifies Windows shortcuts on your desktop. While it creates backups automatically, use at your own risk. Always ensure you have backups of important data.

Project Status & Roadmap

Completion: 100% - Production Ready

What Works

Core Features:

  • ✅ Desktop scanning (Windows .lnk and Linux .desktop files)
  • ✅ SteamGridDB API integration with caching
  • ✅ Async icon downloads with aiohttp
  • ✅ Icon conversion to .ico format (multiple resolutions)
  • ✅ Shortcut icon replacement
  • ✅ Automatic backup creation
  • ✅ One-click restore (--restore latest or specify backup file)
  • ✅ Cross-platform support (Windows and Linux)
  • ✅ UAC shield and shortcut arrow overlay removal (Windows)
  • ✅ Test suite with pytest (80%+ coverage)
  • ✅ CI/CD with GitHub Actions
  • ✅ Proper packaging (setup.py, pyproject.toml)
  • ✅ Command-line interface with multiple options
  • ✅ Configuration management
  • ✅ Error handling and logging
  • ✅ Modular architecture (well-organized source files)

Platform-Specific Features

Windows:

  • ✅ .lnk shortcut icon replacement
  • ✅ UAC shield overlay removal/restoration
  • ✅ Shortcut arrow removal/restoration
  • ✅ Multi-resolution .ico generation (16x16 to 256x256)
  • ✅ COM-based shortcut manipulation

Linux:

  • ✅ .desktop file icon replacement
  • ✅ XDG desktop entry standard compliance
  • ✅ PNG/SVG icon support
  • ✅ Automatic desktop refresh

Known Limitations

Platform Limitations (Not Fixable):

  • ⚠️ .exe Icon Replacement: Cannot replace embedded icons in executables (requires recompiling)
  • ⚠️ .url File Support: Limited icon support for internet shortcuts

Optional Enhancements (Nice-to-Have):

  • GUI interface (currently command-line only)
  • Icon preview before applying
  • Custom icon upload support
  • Folder icon replacement

Linux Usage Examples

Basic usage on Linux:

# Run ICON on Linux
python3 icon_replacer.py

# Auto-apply all icons
python3 icon_replacer.py --auto

# Restore from latest backup
python3 icon_replacer.py --restore latest

# List desktop items
python3 icon_replacer.py --list

Linux .desktop file locations:

  • User desktop: ~/Desktop/
  • System applications: /usr/share/applications/
  • User applications: ~/.local/share/applications/

Current Status

This project is production-ready and feature-complete. All core functionality works reliably:

  • Automatic icon replacement with SteamGridDB artwork
  • Cross-platform support (Windows and Linux)
  • Full backup and restore functionality
  • Comprehensive error handling and logging
  • Well-tested codebase (80%+ coverage)

The tool does exactly what it claims with no critical missing features. Optional enhancements like GUI and preview are nice-to-have but not essential for core functionality.

Created by Wesley Ellis

Found a bug? Have a feature request? Open an issue on GitHub!

About

[100% Complete] Desktop icon replacer using SteamGridDB artwork. Cross-platform (Windows/Linux) with backup/restore, async downloads, and overlay removal.

Topics

python windows automation customization desktop grid-layout icon-management system-utility desktop-icons

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

ICON v1.0.0 - Production Release Latest
Oct 2, 2025

Packages

No packages published

Contributors 2

  •  
  •  

Languages