ImmichSync

Fast, local-first backup and upload companion for your Immich server on macOS.

README · Install · Dev Build · How It Works · Contributing · MIT License

Download  ·  Latest Release

---

README

ImmichSync keeps a local copy of your Immich assets and can watch a local folder to upload new files back to your server. It is designed for reliable syncing with clear status, safety controls, and a menu bar companion.

Thanks to the Immich team for creating such a wonderful tool. ImmichSync is a community project and is not affiliated with Immich.

Install (unsigned build)

1. Download ImmichSync.dmg or ImmichSync.zip from the latest release:
   https://github.com/bjoernch/Immichsync/releases/latest
2. Open the DMG/ZIP and drag ImmichSync.app to /Applications.
3. Important: copy it into /Applications before running any terminal commands or opening the app.
4. If macOS says the app is damaged, run:

xattr -dr com.apple.quarantine /Applications/ImmichSync.app

5. If macOS blocks it, right‑click the app → Open, or allow it in System Settings → Privacy & Security.

If macOS says the app is damaged while copying to /Applications

1. Run this once:

xattr -dr com.apple.quarantine /Applications/ImmichSync.app

2. Go back to the DMG window and drag ImmichSync.app into /Applications again. It should copy and open normally.

Dev build

Run from source (debug)

swift run

Build a clickable app bundle

./scripts/build-app.sh

Output: dist/ImmichSync.app

Build release ZIP/DMG

./scripts/package-release.sh

Outputs: dist/ImmichSync.zip and dist/ImmichSync.dmg

Troubleshooting local builds

• If assets or permissions look wrong, delete the app data folder: ~/Library/Application Support/ImmichSync
• If the menu bar icon does not update, quit and relaunch the app.
• If macOS blocks the app, use Open from the right‑click menu.

How it works

Core features

• Download assets with filters (photos/videos), album filters, and folder structure rules.
• Upload watcher for a local folder (queue + live sync).
• Menu bar status with quick controls.
• Scheduling + background launch agent for unattended syncs.
• Speed stats, status lists, and sync history.
• Optional server duplicate checking before upload.

Download behavior

• Supports flat, year, and year/month folder structures.
• Optional sidecar metadata JSON.
• Optional integrity verification (size + checksum).
• Local duplicate scan with a safety cap for large libraries.

Upload behavior

• Watches the selected folder and optional subfolders.
• Server-side duplicate check can skip already uploaded items.
• Local upload history prevents re-uploads unless cleared.
• All uploads go to the main Immich timeline.

Connection checks

• Quick validation of server URL and API key.
• Displays which features are available based on permissions.

Minimum macOS version

ImmichSync targets macOS 13.0+.

Permissions (full access)

To use all features, grant these API key scopes:

• asset.read
• asset.download
• asset.upload
• album.read
• duplicate.read
• server.about

Credentials and security

• API key is saved locally only after you click Save API Key.
• Keychain storage is available only when Touch ID is enabled.
• Touch ID gating is optional and protects access to the app UI.

Storage locations

• Preferences: UserDefaults
• App data: ~/Library/Application Support/ImmichSync
• Keychain entry: service name ImmichSync (if enabled)

GitHub Releases (automatic)

Push a tag like v1.0.0 and GitHub Actions will build and attach ZIP/DMG to a published release.

git tag v1.0.0
git push origin v1.0.0

Contributing

Issues and pull requests are welcome. If you plan a larger change, please open an issue first so we can align on scope and behavior.

License

MIT License.