ImmichSync

Overview

A Python script to intelligently automate syncing a local folder of images (like screenshots) to your Immich server. It safely handles both local network connections and external connections, preventing duplicates and automatically organizing uploaded assets into a designated album.

Features and Working Mechanism

This script operates in the following sequence during a given run:

1. Environment Loading: Securely loads credentials and configuration variables, including your API key, target folder, and Immich URLs.
2. Network Detection: Pings your local network URL first. If that times out, it seamlessly falls back to your external URL. This is ideal for laptops that frequently switch between home Wi-Fi and outside networks.
3. Album Resolution: Queries the Immich API to find the internal ID associated with the album name specified in your configuration.
4. Local Deduplication: Consults a local history file (immich_upload_history.json) to skip files that have already been uploaded previously by the script in past runs.
5. Server Deduplication & Uploading: Uploads new files along with critical metadata (creation time, modification time). The script properly interprets Immich's API responses to distinguish between a fully new file being created, a soft duplicate that Immich merged, and a hard conflict.
6. Album Linking: Any successfully finalized uploads are subsequently linked to the specified target album.
7. Status Logging: Every operation is logged both to the console and to a local immich_backup.log file, ensuring complete visibility of its operations over time.

Security Considerations

• Authentication: The script authenticates exclusively via the Immich API Key. The key is loaded from a .env file that should be excluded from version control to prevent token leakage.
• Safe Uploads: It uses a purely additive approach. The script reads files from your local system and posts them to the Immich server; it never deletes or modifies your local files.
• Local Storage: Upload history is saved locally within a JSON file to prevent re-upload attempts, ensuring API rate limits and server resources are respected.