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

1. Download and unpack the ZIP archive from the latest Desktop Keeper release.
2. Move the unpacked folder to a private location outside Desktop, Documents, Downloads, iCloud Drive, network volumes, and removable drives; ~/Desktop-Keeper is a suitable choice.
3. Open Terminal and run:

cd ~/Desktop-Keeper
chmod +x Desktop-Keeper.py
./Desktop-Keeper.py setup

If 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:

Common commands:

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 notification ideas that are not current commitments.

The online documentation is maintained in the repository and is not included in release archives.

Contributions are welcome!

Desktop Keeper is available under the MIT Licence.