Immich Backup and Restore: A Doc-Based Guide

Guide · Immich · Doc-based

Doc-based, not yet hands-on tested. This guide is written from the official documentation and has not yet been tested hands-on by us. Check the current official docs before running anything.

Pinned version: Immich v3.3.5 (latest GitHub release, published 2026-10-22 03:12 JST / 2026-10-21 18:12 UTC — https://github.com/immich-app/immich/releases/tag/v3.3.5). Last checked: 2026-10-24.

Transparency note: This guide is based on the official documentation linked below. It was not hands-on tested by us. Commands are copied from the official docs as of the date above; always check the current docs before running them.

The Immich docs recommend a 3-2-1 backup strategy and warn that their instructions only show what to back up: "You still need to take care of using an actual backup tool" (Backup and Restore). This guide covers what to save, how to restore it, and how to run a restore drill so you know your backup works.

What to back up

1. The database. Immich keeps file paths and metadata in Postgres and "does not scan the library folder, so database backups are essential."

2. The files. The docs recommend backing up all of UPLOAD_LOCATION. The critical originals are in:

If you skip thumbs and encoded-video, you'll need to rerun the thumbnail and transcoding jobs after a restore. Because the dumps live in UPLOAD_LOCATION/backups, backing up the whole UPLOAD_LOCATION captures both the database dumps and the files.

Offsite copy: use any backup tool you trust (for example restic or Borg) to send UPLOAD_LOCATION to a second location. We aren't giving tool-specific commands here because they aren't part of Immich's docs. Follow your tool's own documentation. (Editor: add a restic section sourced from restic.readthedocs.io before publishing, if wanted.)

This page contains affiliate placeholders. See our affiliate disclosure.

[AFFILIATE: DigitalOcean — offsite VPS/object storage target]

Manual CLI dump (optional)

From the official docs (Linux):

bash
docker exec -t immich_postgres pg_dump --clean --if-exists --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME> | gzip > "<BACKUP_DIR>/dump.sql.gz"

⚠️ Caution: a database dump alone is not a backup of your photos. You also need a copy of UPLOAD_LOCATION, and a backup only counts once you have restored it on a separate machine. We haven't run this drill ourselves yet.

The restore drill (do this on a separate machine or VM)

Don't practice on your live server. The docs' "Restore from Onboarding" path is designed for a fresh install:

  1. On the test machine, download and fill in .env and docker-compose.yml as in the install guide. Use the same Immich version as the backup, because restoring from a different version may require migrations.
  2. Copy the backed-up backups, encoded-video, library, profile, thumbs, and upload folders into the new UPLOAD_LOCATION. If you used external libraries, use the same mount structure as before.
  3. Run docker compose up -d.
  4. On the welcome screen, click Restore from backup. Immich enters maintenance mode and shows integrity checks for your folders. Review them, then click Next.
  5. Pick a backup or upload a .sql.gz file, then click Restore.

Immich creates a restore point, restores the backup, runs migrations if needed, and runs a health check. If the restore fails, it rolls back automatically.

Drill checklist (our suggestion, not from the docs): log in, compare asset counts with production, open some old originals, play a video, and check albums and faces. Write down the date and how long the restore took.

On an existing install, you can also restore from Administration > Maintenance > Restore database backup. This wipes the current database, although a restore point is created first.

CLI restore (advanced)

**⚠️ WARNING: the official CLI restore begins with docker compose down -v, which deletes all Immich data (the docs mark it "CAUTION! Deletes all Immich data to start from scratch"). Never run it on your production server.**

The docs also give a command-line restore. Copy it verbatim from the official page rather than from here, and only run it on the test machine: https://docs.immich.app/administration/backup-and-restore#restore-via-command-line

Sources

Related