Immich Backup and Restore Placeholders

---

This page defines all placeholders used across the Immich backup & restore guide.
Anywhere you see something like <MASTER_DIR> or <DB_CONTAINER>, replace it with the value that matches your setup..

Example

If your Immich lives in /volume1/docker/immich, then everywhere the guide says
cd <MASTER_DIR>
you actually run:
cd /volume1/docker/immich

---

Core paths

These are used throughout Part 0–4.

Placeholder	Meaning	Typical value / example
<MASTER_DIR>	Immich “master” folder containing docker-compose.yml and subfolders.	/volume1/docker/immich
<DB_DATA_DIR>	Folder where Postgres stores its data.	<MASTER_DIR>/db
<UPLOAD_LOCATION>	Root upload/media location used by Immich (env var in .env).	By default: <MASTER_DIR>/upload

Standard folder layout (Docker default)

As used in [Part 3 – Basics]:

<MASTER_DIR>/
  cache     # <<< Contains your cache
  db
  micro
  redis
  upload    # <<< Contains library, uploads, profile, backups, etc.

Inside upload/ Immich stores:

• upload/library – original assets

• upload/upload – uploaded assets

• upload/profile – profile images / related data

• upload/backups – automatic database dumps (*.sql.gz)

---

Backup & dump files

Placeholder	Meaning	Typical value / example
<DUMP_FILE>	Full path to your database dump (*.sql.gz).	<MASTER_DIR>/upload/backups/immich-db-backup-20250930T000000-v1.143.1-pg16.10.sql.gz

This value is used in restore commands in Part 4 – Restoring your Database.

---

Database container & credentials

These placeholders must match your docker-compose.yml and .env:

Placeholder	Meaning	Typical value / example
<DB_CONTAINER>	Name of the Postgres container.	immich_postgres or Immich-DB
<DB_NAME>	Database name used by Immich.	immich
<DB_USER>	Database user that owns the Immich database.	immichuser

You see these in commands like:

sudo docker exec -it <DB_CONTAINER> psql --dbname=<DB_NAME> --username=<DB_USER> ...
docker exec -it <DB_CONTAINER> pg_amcheck --username=<DB_USER> ...

Make sure the values line up with:

• services.postgres.container_name in your docker-compose.yml

• DB_DATABASE_NAME, DB_USERNAME (or similar) in your .env

---

How to adapt this guide to your setup

1. Pick your master folder

   <MASTER_DIR> = /volume1/docker/immich

2. Check your DB container name

   From your host:

   docker ps --format "table {{.Names}}\t{{.Image}}"

   Find the Postgres container and map the name to <DB_CONTAINER>.

3. Confirm DB name and user

   In your .env or docker-compose.yml, look for variables like:

   DB_DATABASE_NAME=immich
   DB_USERNAME=immichuser

   Map these to <DB_NAME> and <DB_USER>.

4. Locate your dump file

   List the backup folder:

   ls <MASTER_DIR>/upload/backups

   Choose the correct *.sql.gz file and use it as <DUMP_FILE>.

Once you’ve done this once, you can speed-read the rest of the guide and mentally substitute your real values wherever a placeholder appears.

Next Part 0. Immich backup restore - Frontpage