Desktop Keeper saves and restores Finder desktop icon positions for each display setup.
It runs as a per-user macOS LaunchAgent, autosaves stable icon changes, uses only built-in macOS tools, and keeps its data local.
- macOS with Finder
- Python 3 available as
python3 - Permission for Terminal or Python to automate Finder
- Download and unpack the ZIP archive from the latest Desktop Keeper release.
- Move the unpacked folder to a private location outside Desktop, Documents, Downloads, iCloud Drive, network volumes, and removable drives;
~/Desktop-Keeperis a suitable choice. - Open Terminal and run:
cd ~/Desktop-Keeper
chmod +x Desktop-Keeper.py
./Desktop-Keeper.py setupIf the executable bit is not preserved, run python3 Desktop-Keeper.py setup instead. If Python 3 is missing, install it from python.org.
Allow Finder automation if macOS asks. setup saves the current layout, installs a private runtime copy, and starts the background helper.
After setup, Desktop Keeper normally needs no attention. When the helper starts or the display setup changes, it restores a recognised saved layout and verifies the restored positions for the autosave delay before accepting later changes. An unrecognised display fingerprint uses the current layout as its initial baseline unless that display setup was explicitly deleted.
If the desktop happens to appear unexpectedly right-aligned after sign-in or a macOS update, do not move any icons while that arrangement remains visible. One icon movement can make the entire visible arrangement eligible for a later autosave, particularly if macOS reports an unrecognised display fingerprint. Check status, doctor, and the logs, then use restore if necessary; see troubleshooting.
Default timings:
| Setting | Default |
|---|---|
| Display check | every 5 seconds |
| Restore delay after display change | 2 seconds |
| Autosave delay after icon changes | 8 stable seconds |
Common commands:
| Command | Purpose |
|---|---|
./Desktop-Keeper.py |
Open the optional text menu |
./Desktop-Keeper.py status |
Show the version, current layout, helper health and timing, and notification level |
./Desktop-Keeper.py doctor |
Check permissions, paths, saved layouts, and logs |
./Desktop-Keeper.py notifications important |
Enable important watcher notifications |
./Desktop-Keeper.py save --label "Main setup" |
Save the current layout manually |
./Desktop-Keeper.py delete --current |
Delete the saved layout for the current display setup |
./Desktop-Keeper.py restore --dry-run |
Preview a restore without moving icons |
./Desktop-Keeper.py restart |
Update and restart the background helper |
./Desktop-Keeper.py uninstall |
Remove the helper, saved layouts, notification settings, and logs |
Notifications are off by default. Interactive Setup shows the current level and asks whether Desktop Keeper should use notifications before setup is confirmed. You can also choose Notifications in the text menu, or show the current level and select off, errors, important, or all explicitly:
./Desktop-Keeper.py notifications
./Desktop-Keeper.py notifications importanterrors reports watcher problems that need attention. important also confirms that a restored layout has been verified. all additionally reports initial-layout saves and autosaves. Notifications are sent only by the background helper or foreground watch command, use no explicit sound, and never replace the activity and error logs.
Desktop Keeper submits notifications through /usr/bin/osascript. Under System Settings → Notifications, look for a sender entry named osascript, Script Editor, Python, or Terminal; the current generic transport does not guarantee a Desktop Keeper entry. macOS notification or Focus settings may silence or hide submitted notifications. Suppression or delivery failure never interrupts restore, verification, autosave, Store access, or the watcher.
Deleting a saved layout leaves that display setup unmanaged so the background helper does not recreate it as a new baseline. A previously running helper continues managing other saved layouts and is restarted automatically if deletion requires it; no immediate user action is needed. Run save or setup for the deleted display setup only when you want Desktop Keeper to manage it again.
See the complete usage and command guide for every command, option, file location, and uninstall detail.
In an 88-second steady-state measurement on an Apple silicon Mac with the default five-second interval, the persistent Python process used about 11.6 MiB of resident memory. Including short-lived macOS helpers, median resident memory remained 11.6 MiB, the 95th percentile was 36.5 MiB, and the peak was 37.4 MiB. CPU use was 0% in the median sample and about 1.6% of one core on average, with brief peaks while system_profiler and osascript ran.
These figures describe one measured system, not a fixed requirement. See the measurement method, conditions, and limitations.
Desktop Keeper has no network code and no third-party Python packages. It stores display metadata, desktop item names, and icon coordinates locally; it does not read desktop file contents, move or delete desktop items, or upload data.
See privacy and limitations for the stored fields, local paths, Finder behaviour, and display-matching limits.
Choose the guide that matches what you want to do:
- Usage and commands explains setup behaviour, daily use, every command and option, file locations, and uninstall steps.
- Troubleshooting walks through diagnostics, logs, macOS permissions, missing Python, and icon-placement problems.
- Privacy and limitations describes the data stored locally, the files Desktop Keeper changes, and known display-matching limits.
- Resource usage presents the measured CPU and memory figures, test conditions, and limits of the measurement.
- Possible future directions outlines potential packaging and dedicated notification-identity ideas that are not current commitments.
The online documentation is maintained in the repository and is not included in release archives.
Desktop Keeper is available under the MIT Licence.