thumbdump

Last-resort recovery tool for Immich instances where the original uploaded files have been lost. Downloads the best available preview files and writes back all recoverable metadata (EXIF, GPS, timestamps) into the recovered files.

This tool is read-only with respect to your Immich server. It never writes anything back.

Run

Create an empty directory on your host, then mount it to /output:

mkdir recovery

docker run --rm -it \
  -v $(pwd)/recovery:/output \
  ghcr.io/bo0tzz/thumbdump \
  --server https://immich.example.com \
  --api-key YOUR_API_KEY

The container writes to /output by default. On startup it will interactively ask which preview quality to download and which libraries to include.

To run non-interactively:

docker run --rm \
  -v $(pwd)/recovery:/output \
  ghcr.io/bo0tzz/thumbdump \
  --server https://immich.example.com \
  --api-key YOUR_API_KEY \
  --preview-size preview \
  --all-libraries

Multiple users

Repeat --api-key once per user, or supply a keys file:

docker run --rm \
  -v $(pwd)/recovery:/output \
  -v $(pwd)/keys.txt:/keys.txt:ro \
  ghcr.io/bo0tzz/thumbdump \
  --server https://immich.example.com \
  --keys-file /keys.txt \
  --all-libraries

keys.txt — one API key per line, # comments ignored:

# alice
abc123...
# bob
def456...

Options

Flag	Default	Description
--server <url>	required	Immich server URL
--api-key <key>	required*	API key; repeatable for multiple users
--keys-file <path>	—	File with one API key per line
--preview-size preview|thumbnail	interactive	Skip quality prompt
--all-libraries	false	Skip library selection prompt
--concurrency <n>	5	Parallel downloads per user

* Either --api-key or --keys-file is required.

Output

recovery/
  <username>/
    <originalFileName>.jpg   # recovered file with metadata written back
  manifest.json              # per-asset status (assetId, path, errors, …)
  summary.txt                # counts: scanned / downloaded / metadata-written / skipped / failed
  skipped.log                # assets with no usable preview

A summary is also printed to stdout at the end of the run.