Feat: Add Snapchat import adapter

[jakobbjelver]

In the light of Snapchat's more or less recent changes to included free cloud storage (from unlimited to 5 GB), more people are looking to make the switch in order to avoid losing their media library or pay the monthly subscription fee to Snapchat - effective September 2026.
Some projects targeted for this already exist, but they are either broken, paid/closed source, Windows-only, or lacks crucial features. And none are of course compatible with Immich (as far as I know).

I believe adding a Snapchat adapter to immich-go, which otherwise is a great tool for getting started and making the switch to Immich, is a valid and timely addition.

Since the Snapchat "My Data" export data structure is not as straightforward as the Google Photos "Takeout" feature's is, this was a bit more complicated to accomplish - this is why my assessment concluded a Snapchat adapter would be the most natural approach. Also, the standard duplicate detection was found to be insufficient - most likely because of how Snapchat differs in how it saved to the local camera roll and to its own cloud storage - which was fixed with an optional option/parameter: --conservative-duplicates which worked for my case.

The following code written with assistance from an AI agent, since I myself am not literate in the Go language. But I do work as a software engineer, so I can vouch for its consistency in terms of general code quality. Although I would appreciate someone sufficient in the language and framework to give some feedback or corrections. I could have just kept it for myself, since it helped me successfully migrate my Snapchat library to Immich, but since I enjoyed this project so much for my initial Google Photos migration, I wanted to give back to it.

I hope this can be useful for someone else out there with the same circumstances as me.

Summary

• Add first-class Snapchat support with new commands:
  • upload from-snapchat
  • archive from-snapchat
• Parse Snapchat json/memories_history.json, map metadata by both sid and mid, and import Memories media from memories/*-main.*.
• Merge Snapchat -overlay.png into corresponding -main media (images in-process, videos via ffmpeg), with safe fallback to main media when merge fails.

Duplicate detection improvements

• Add --conservative-duplicates mode for upload.
• Keep existing checksum-first matching, then add conservative matching by type + size + capture-time window.
• Add Snapchat-aware fuzzy matching for real-world migrated libraries:
  • local YYYY-MM-DD_<id>-main.ext ↔ server Snapchat-*
  • type-aware matching (image/video)
  • day-based matching with ambiguity rejection
  • tuned thresholds to improve recall while avoiding risky false positives.

Tracking and stability fixes

• Fix merged Snapchat asset lifecycle tracking mismatch by adding fallback finalization lookup in asset tracker:
  • handles synthetic keys like snapchat-merged:<source>:merged
  • applies to processed/discarded/error transitions
• This removes SetProcessed: asset not found errors for merged assets seen in previous logs.

Tests

• Add/extend Snapchat parser tests:
  • verify metadata mapping for both sid and mid
• Add Snapchat duplicate matcher tests:
  • image and video fuzzy matches
  • non-Snapchat negative case
  • adjacent-day positive case
  • ambiguous candidate rejection
  • out-of-window rejection
• Add asset tracker regression tests for merged key fallback:
  • processed/discarded/error transitions.

Notes from dry-run validation

• Latest dry-run log indicates:
  • no SetProcessed/SetDiscarded/SetError: asset not found tracker errors
  • duplicate detection significantly improved (server has duplicate events observed at scale)
• Run remained interruptible and behaved correctly under --dry-run.

Example usage

immich-go upload from-snapchat \
  --server="http://localhost:2283" \
  --api-key="<API_KEY>" \
  --conservative-duplicates \
  ./DATA/mydata~*.zip

[ozjuly19]

I can attest to this I just used the source from the merging repo to import ~18gb of snapchat memories to my 2.7.5 instance. Thank you so much that would've been a pain!

[echoix]

I saw a recent release of https://github.com/leofleischmann/chats-and-memories-vault-for-snapchat-export that I used last month for this. That new release allows to sync to an existing immich server, instead of having one created with the docker compose, and then having to use immich go to copy from server to server (like I did).