Skip to main content

Switching Back to Immich

This guide walks through switching a Gallery instance back to upstream Immich. It runs a cleanup script that strips Gallery-only schema from your database so that the vanilla immich-server image will start against it.

danger

This is a one-way, destructive operation. The cleanup script drops every Gallery-only table and column. Anything stored only in Gallery-specific features is permanently lost. At minimum, you will lose:

  • Shared spaces (members, assets, person clusters, libraries, activity, audit history)
  • User groups and memberships
  • Classification categories and prompts
  • Pet detection results, and every individual pet you named through pet recognition
  • Asset duplicate checksums
  • Library sync state
  • Favorites belonging to anyone other than the asset's owner (see note below)

Assets you uploaded through Gallery are preserved, as long as they exist in Immich-native tables (which is the normal case for every file uploaded via the web or mobile app).

The right answer is to restore the pg_dump you took before switching to Gallery. Use this script only if you skipped that step.

1. Back up your database​

Take a pg_dump first, even if you plan to run the cleanup script. It is your way back if something goes wrong.

docker exec immich_postgres pg_dump -U postgres -d immich \
  > gallery-pre-revert-$(date +%F).sql

Keep that file outside your Gallery install directory.

The cleanup script takes ACCESS EXCLUSIVE locks on many tables, so a running server will either deadlock with it or race it. Stop every app container, but keep the database up so the script can connect:

docker compose stop immich-server immich-machine-learning

Leave immich_postgres (and immich_redis, if you run it) running.

3. Download the cleanup script​

Use the script attached to the release you are actually running, not the copy on the main branch. Each script targets the exact set of Gallery-only tables, columns and fork migrations for its own release. main is always ahead, so its copy can drop things your schema does not have, or miss things it does, if your instance is even one release behind.

Find your version first: run immich-admin version in the immich_server container, or click the version number at the bottom of the sidebar in the Gallery web UI to open the About dialog.

Then open that version's page on the Gallery releases page, for example https://github.com/open-noodle/gallery/releases/tag/v5.4.0, and download the revert-to-immich.sql asset attached to it, either from the browser or with curl:

curl -LO https://github.com/open-noodle/gallery/releases/download/v5.4.0/revert-to-immich.sql

Replace v5.4.0 with your own version. Every release since this asset was introduced ships one. If yours predates it, upgrade to the nearest later release first and use the script attached there.

Read the script header first. It lists every table and column the script will drop.

4. Run the cleanup script​

Copy the script into the postgres container and run it with psql:

docker cp revert-to-immich.sql immich_postgres:/tmp/
docker exec immich_postgres psql -U postgres -d immich \
  -v ON_ERROR_STOP=1 \
  -c "SET gallery.revert_token = 'i_accept_data_loss';" \
  -f /tmp/revert-to-immich.sql

Notes:

  • The gallery.revert_token setting is a deliberate speed-bump. The script refuses to run without it, so you cannot execute it by accident.
  • ON_ERROR_STOP=1 is important: without it, psql will keep going past the first error and leave the database in a half-cleaned state. The script wraps everything in a transaction, so a mid-script failure rolls the whole thing back.
  • On success, the last line of output reads: 
    NOTICE: revert-to-immich: cleanup finished. Switch your image to ghcr.io/immich-app/immich-server and start the stack.

5. Switch your compose file to upstream Immich​

Edit your docker-compose.yml and replace every reference to the Gallery image with the upstream immich-server image. Pin a version close to the Immich release Gallery was last rebased from. You can find it in branding/config.json in the Gallery repository, under upstream.version.

docker-compose.yml
services:
  immich-server:
    # image: ghcr.io/open-noodle/gallery-server:${IMMICH_VERSION:-release}
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
...
  immich-machine-learning:
    #image: ghcr.io/open-noodle/gallery-ml:${IMMICH_VERSION:-release}
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}

Upstream Immich uses the same postgres image as Gallery, so no database image change is needed.

If you set any Gallery-only environment variables, remove them from your .env file, or upstream Immich will log warnings about unknown settings.

.env
#IMMICH_VERSION=v5
IMMICH_VERSION=v3

6. Start the stack​

docker compose up -d
docker compose logs -f immich-server

Watch the server log. A successful boot ends with the usual Immich startup banner and no migration errors. If you see a "missing migration" or "corrupted migrations" error, the cleanup did not complete. Restore your pg_dump from step 1 and open an issue on the Gallery repository with the full error output.

What was removed​

Here is what the cleanup script changes:

  • It drops the Gallery-only tables shared_space*, album_space_asset*, library_user, library_audit, library_asset_audit, shared_space_library*, face_identity*, face_repair*, pet_search, user_group, user_group_member, classification_category, classification_prompt_embedding, storage_migration_log, asset_duplicate_checksum, asset_favorite and asset_favorite_audit.
  • It drops the Gallery-added columns person.type, person.species, asset_job_status.petsDetectedAt, asset_job_status.classifiedAt and library.createId.
  • It restores asset.isFavorite, an upstream Immich column Gallery moved into the asset_favorite overlay so each space member can favorite independently, before dropping asset_favorite, and backfills it from the overlay — but only for the asset's owner. Favorites belonging to anyone else (for example, a shared-space viewer who favorited another member's photo) have no equivalent in plain Immich's single-favorite-flag model and are discarded. Your own favorites on your own assets are preserved.
  • It drops the Gallery-only functions and triggers that reference the dropped tables.
  • It strips the classification key out of the system-config row in system_metadata.
  • It deletes fork migration rows from kysely_migrations and migration_overrides, so upstream Immich's migrator does not see them as unknown migrations.
  • Where needed, it rolls back upstream migrations that Gallery pulled in after the currently supported Immich tag. Gallery may be rebased onto upstream commits newer than the Immich release you switch back to, so the script also removes those migration rows and reverses their schema changes before vanilla Immich starts.

The script header documents each step in detail.