SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor

Immichのバージョンアップ手順：写真ライブラリを壊さず安全に更新する

Immichをdocker composeで安全にバージョンアップする手順。リリースノートの読み方、アプリを先に更新する理由、IMMICH_VERSIONの固定、ダウングレード不可への備え、移行中のログの見方まで。

結論：Immichのバージョンアップは「読む、アプリ、バックアップ、pull、待つ」の順

Immichのバージョンアップで写真ライブラリを壊さないコツは、コマンドより順番です。公式ドキュメント（2026年9月19日確認）が示す順番は、リリースノートを読む、モバイルアプリを先に更新する、データベースとライブラリをバックアップする、docker compose pull && docker compose up -d を実行する、マイグレーションが終わるまで待つ、の五つです。打つコマンドは実質2行しかありません。壊れるのは、その前後を飛ばしたときです。

Immichにはダウングレードがありません。新しいバージョンがデータベースを書き換えたあとで古いイメージに戻しても、サーバーは起動を拒否します。だからバックアップが pull より前にあります。以下、各手順で何を確認し、画面やログに何が出れば正常なのかを順に見ていきます。

なぜImmichのアップデートは慎重さが要るのか

Immichはセマンティックバージョニング（<major>.<minor>.<patch>）を採用していて、破壊的変更（breaking change）はメジャーバージョンでだけ入る方針です。2026年9月19日時点の最新版は v3.2.2（2026年9月15日公開）で、現在のメジャーである v3.0.0 は2026年7月2日に公開されました。

慎重さが要る理由の一つ目は、マイグレーションが自動で走ることです。サーバーは新しいイメージで起動した瞬間に、データベースのスキーマを自分で書き換えます。「実行しますか」という確認はありません。そしてImmichは、一度書き換えたデータベースを古いバージョンに戻す手段を提供していません。公式ドキュメントは「同じマイナーバージョン内であっても、以前のバージョンへのダウングレードはサポートしない」と明記しています。

二つ目は、モバイルアプリとの互換性です。公式の説明では、アプリは「現在と一つ前のメジャーバージョン」に対応しますが、サーバーは「自分と同じメジャーバージョン」にしか対応しません。サーバーを先に上げると、アプリが取り残されます。

手順1：リリースノートと changelog:breaking-change ラベルを読む

更新前に読む場所は二つです。GitHubのリリースページと、changelog:breaking-change ラベルの付いたディスカッション一覧です。後者には v3.0.0、v2.0.0、v1.137.0、v1.136.0、v1.133.0 のように、手作業が必要だったリリースだけが並びます。数は少ないので、自分の現在のバージョンより新しいものを全部読んでも数分で済みます。

見るポイントは二点です。docker-compose.yml を書き換える必要があるか。.env に追加や削除の項目があるか。たとえば v3.0.0 のリリースノートには、次の差分がそのまま載っています。

- IMMICH_VERSION=v2
+ IMMICH_VERSION=v3

これを .env に反映しないと、v2 に固定した環境では docker compose pull を何回打っても v2 系の最新版しか降ってきません。裏を返せば、固定しているからこそ「読んでから上げる」余裕が生まれます。

自分の docker-compose.yml が公式版からどれだけ離れているかは、diff で分かります。

cd ~/immich-app
wget -O docker-compose.new.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
diff docker-compose.yml docker-compose.new.yml

差分がなければ何も出力されません。image: の行に差分があれば、そのリリースでイメージが変わったということです。特に database サービスの image: は要注意で、後述する VectorChord への移行がまさにこれでした。確認が終わったら docker-compose.new.yml は削除して構いません。

手順2：サーバーより先にモバイルアプリを更新する

順番はアプリが先、サーバーが後です。アプリは一つ前のメジャーまで面倒を見るので、アプリを v3 に上げてもサーバーが v2 のままなら動きます。逆にサーバーだけ v3 に上げると、v2 のアプリはサーバーと同じメジャーではないので拒否されます。

iPhone なら App Store、Android なら Google Play か F-Droid で Immich を更新します。家族の端末も忘れずに。サーバーを上げた直後に「家族のアプリが全部つながらなくなった」というのが、順番を逆にしたときの典型的な症状です。

アプリを開いて、サーバーに接続できることを確認してから次に進みます。

手順3：データベースとライブラリをバックアップする

バックアップは docker compose pull の前に取ります。後ではありません。データベースのダンプの取り方とライブラリの退避先は Immichのバックアップと復元の手順 にまとめてあるので、ここでは繰り返しません。

確認だけしておきます。今日の日付のダンプファイルが存在すること。UPLOAD_LOCATION のディレクトリがコピー先に揃っていること。この二つが揃っていれば、更新が失敗しても元に戻せます。ダウングレードができない Immich では、これが唯一の「戻る」手段です。

手順4：.env の IMMICH_VERSION を決める

grep IMMICH_VERSION .env

IMMICH_VERSION=v3 のような行が出れば固定されています。何も出なければ、docker-compose.yml の ${IMMICH_VERSION:-release} によって release タグが使われています。

選べるタグは次の通りです。

  • release：常に最新の安定版を指します。v4.0.0 が公開された瞬間、次の pull で v4 に上がります。破壊的変更を読む前にメジャーが変わり得る、ということです。
  • v3：v3 系の最新安定版を指すメタタグです。公式ドキュメントによれば、メタタグはリリース候補（RC）を追いません。パッチとマイナーは自動で取り込み、メジャーは自分で .env を書き換えるまで変わりません。
  • v3.2.2：特定のバージョンに完全固定します。バグ修正を受け取るたびに .env を書き換える必要があります。

おすすめは v3 です。バグ修正は自動で入り、メジャーの壁だけは手で越える。「読んでから上げる」を仕組みで保証する設定です。2026年9月時点で配布されている example.env の初期値も次のようになっています。

# The Immich version to use. You can pin this to a specific version like "v2.1.0"
IMMICH_VERSION=v3

手順5：docker compose pull と up -d、そして docker image prune

cd ~/immich-app
docker compose pull && docker compose up -d

pull が .env のタグに合う新しいイメージを取得し、up -d がイメージの変わったコンテナだけを作り直します。docker compose restart ではイメージが更新されない理由は docker compose restart と up -d の違い で説明しています。

起動後の確認は二つです。

docker compose ps
curl -s http://localhost:2283/api/server/version

docker compose ps の STATUS 列が Up ... (healthy) なら起動完了です。(health: starting) の間はまだマイグレーション中なので、手順6へ進みます。/api/server/version は認証なしで応答するエンドポイントで、{"major":3,"minor":2,"patch":2} のような JSON が返ります。この数字が目標のバージョンと一致していれば、正しいイメージで動いています。

古いイメージはディスクに残り続けます。

docker image prune

確認を求められるので y で答えます。これは、どのコンテナからも参照されていないイメージだけを消します。動いているコンテナのイメージは消えません。Immich のサーバーと機械学習のイメージは大きいので、VPS のディスクが小さいなら更新のたびに実行する価値があります。

手順6：マイグレーションが終わるまで待つ。再起動しない

docker compose logs -f immich-server

新しいバージョンで最初に起動したとき、サーバーはデータベースのスキーマを更新します。ログには次の行が順に出ます（マイグレーション名は環境とバージョンで変わります）。

Running migrations
Migration "1752267649968-StandardizeNames" succeeded
Finished running migrations

Finished running migrations が出るまで、docker compose down も docker compose restart も打たないでください。途中で止めても得るものはありません。次の起動でまた同じ処理が最初から走り、待ち時間が増えるだけです。

大きなライブラリでは、そのあとにベクトルインデックスの再構築が走ります。サーバー自身が「再起動するな」とログに書きます。

Reindexing clip_index (This may take a while, do not restart)
Reindexed clip_index
Reindexing face_index (This may take a while, do not restart)
Reindexed face_index

公式ドキュメントも、Reindexing clip_index や Reindexing face_index で長時間止まって見えるのはエラーが出ていない限り正常だと書いています。この間、docker compose ps の STATUS は (health: starting) のままです。API はマイグレーションが終わるまで応答を始めないので、ヘルスチェックが通らないのは設計通りです。所要時間は公式の説明で「数秒から数分」、ライブラリの規模で変わります。ログに If using Docker, consider increasing shm_size for the database. が出るなら、データベースコンテナの共有メモリが足りていません。目安は Immichに必要なRAMとストレージの量 を参照してください。

サーバー側とは別に、アプリ側にも「移行」があります。v1.142.0（2025年9月12日公開）以降のアプリは、更新後の初回起動時に端末内のデータベースを新しいタイムライン形式に作り直します。その間、画面に Data migration in progress... Please wait and don't close this page の趣旨の表示が出ます（日本語UIでは対応する日本語で表示されます）。これは端末の中だけの処理で、サーバーには何もしていません。開発者の説明では、止まったように見えてもアプリを再起動すれば必要なデータを作り直すので、サーバー側の移行とは違って再起動しても壊れません。時間がかかるだけです。

ダウングレードはできない：バックアップが先である理由

「新しいバージョンで不具合が出たので前のタグに戻す」は、Immich では通りません。古いイメージで起動すると、サーバーは次のエラーを出して止まります。

Migration "<名前>" was already applied to this database but is not in this version of Immich (<バージョン>). This usually means the database was migrated by a newer version. Downgrades are not supported.

データベースに「このバージョンのサーバーが知らないマイグレーション」が記録されているからです。古いバージョンにパッチをさかのぼって当てる（backport）ことも、公式はやらないと明言しています。戻したければ、手順3で取ったダンプから復元し、ライブラリを退避したコピーに戻し、.env を前のバージョンに固定して起動し直します。つまり、バックアップこそが Immich で唯一使えるダウングレード手段です。

盲目的な pull が通らなかった例：pgvecto.rs から VectorChord への移行

「docker compose pull さえ打てば済む」が通用しなかった代表例が、2025年5月21日公開の v1.133.0 です。このバージョンで、ベクトル検索の拡張が pgvecto.rs から VectorChord に変わりました。変わったのはデータベースコンテナのイメージで、Immich 本体のイメージだけを pull しても追いつきません。

docker-compose.yml の database サービスを、旧イメージから新イメージに書き換える指示でした。

# 旧（pgvecto.rs）
image: docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0
# 新（2026年9月時点で公式 compose が指すタグ。v1.133.0 当時は vectorchord0.3.0）
image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0

新しいタグに pgvectors0.2.0 が残っているのは、旧データを読んで移行するためです。同時に、database サービスの healthcheck: と command: のブロックは削除する指示でした。どちらもイメージ側に組み込まれたからです。

pull だけ打った人はどうなったか。v1.133.0 当時の Immich は利用できる拡張を自動検出したので、旧イメージのままでも動きました。ところが 2026年7月の v3.0.0 で pgvecto.rs のサポートが打ち切られました。v3.0.0 のリリースノートには「v1.133.0 より前の Immich を動かしていて、まだ移行していないなら、先に移行ガイドを見ること」という警告が載っています。一年以上前の変更を飛ばしたまま v3 に上げると、そこで止まります。

自分が対象かどうかは、次の二行で分かります。

grep -n 'pgvecto-rs' docker-compose.yml
grep -n 'DB_VECTOR_EXTENSION' .env

どちらも何も出力せず、database の image: が ghcr.io/immich-app/postgres を指していれば、既に VectorChord です。この節は関係ありません。tensorchord/pgvecto-rs が出てきたら、公式の移行手順に従い、バックアップを取ってからイメージを差し替えます。移行後は v1.133.0 未満に戻せません。

Watchtower で Immich を自動更新してはいけないのか

「immich watchtower」で検索する人は多く、後悔する人も多いです。Watchtower はコンテナのイメージを定期的に確認し、新しければ勝手に pull して作り直すツールです。公式のアップグレードページは Watchtower について何も書いていません。禁止も推奨もしていない、というのが事実です。

それでも合わない理由は、ここまでの手順から導けます。Immich は「上げる前にリリースノートを読め」と要求し、「上げたら戻せない」と明記しています。Watchtower はこの二つのどちらも守れません。読まずに上げ、戻せない変更を深夜に適用します。release タグと組み合わせると、v4.0.0 が出た夜にメジャーアップデートがアプリより先に適用され、翌朝は家族全員のアプリが接続を拒否されます。

v3 に固定していれば、Watchtower が上げるのはパッチとマイナーだけになります。それでもサーバーがアプリより先に上がる問題は残るので、Immich は手で更新するべきです。Watchtower を他のスタックで使っているなら、Immich の各サービスにラベルを付けて対象から外せます。docker-compose.override.yml に書いておけば、公式の docker-compose.yml を差し替えるたびに書き直さずに済みます。

services:
  immich-server:
    labels:
      - com.centurylinklabs.watchtower.enable=false
  immich-machine-learning:
    labels:
      - com.centurylinklabs.watchtower.enable=false

アプリだけ更新されて「サーバーが古い」と言われたら

日本の読者が最初にぶつかるのは、たいていこの症状です。App Store や Google Play がアプリを自動更新し、開いた瞬間に「サーバーが更新されてません。最新のバージョンに更新してください」（英語UIでは Server is out of date. Please update to the latest major version.、文言はアプリのバージョンで多少変わります）という警告が出ます。メジャーの互換範囲を外れてログインすら通らない場合は Your app major version is not compatible with the server! になります。

答えは一行です。サーバー側で docker compose pull && docker compose up -d を打ってください。ストアからアプリを古いバージョンに戻す手段はないので、追いつけるのはサーバーだけです。ただし打つ前に、バックアップとリリースノートの確認だけは飛ばさないでください。

別のサーバーへの引っ越しは更新ではない

「immich サーバー 移行」で来た人へ。VPS を乗り換える、ディスクを変える、といった引っ越しは、バックアップして新しい場所で復元する作業です。上の pull の手順では扱えません。手順は Immichのバックアップと復元の手順 に、引っ越し先の新規構築は VPS に Immich を立てて Google フォトの代わりにする手順 にあります。Immich に限らない Docker Compose スタック全体の更新とバックアップの考え方は Docker Compose スタックのバックアップとアップグレード を参照してください。

FAQ：Immich のアップデートでよくある質問

Immich のアップデート後、health: starting のまま進みません。壊れましたか？

docker compose logs -f immich-server を見てください。Running migrations や Reindexing clip_index (This may take a while, do not restart) が出ていてエラーがなければ正常で、終わるのを待つだけです。API はマイグレーション完了まで応答を始めないので、ヘルスチェックはそれまで通りません。Migration "..." failed や PostgresError が出ている場合だけ異常で、その時は再起動を繰り返さず、エラー行をそのまま GitHub のディスカッションで検索してください。

IMMICH_VERSION は release と v3 のどちらにすべきですか？

v3 です。v3 は v3 系の最新安定版だけを指すメタタグで、パッチとマイナーは自動で取り込み、リリース候補は追わず、メジャーは .env を書き換えるまで変わりません。release は次のメジャーが出た瞬間にそれを指すので、リリースノートを読む前に破壊的変更が入ります。2026年9月時点の example.env の初期値も v3 です。

新しいバージョンで不具合が出ました。前のバージョンに戻せますか？

イメージのタグを戻すだけでは戻せません。古いサーバーは Downgrades are not supported. を含むエラーを出して起動を拒否します。戻す方法は、更新前に取ったデータベースのダンプとライブラリのコピーから復元し、.env を前のバージョンに固定して起動し直すことだけです。更新前のバックアップが必須なのはこのためです。

Watchtower で Immich を自動更新してもいいですか？

公式ドキュメントは Watchtower に触れていません。ただし Immich は更新前にリリースノートを読むことを求め、ダウングレードを認めていないので、読まずに自動で pull する仕組みとは相性が悪いです。v3 に固定すれば影響はパッチとマイナーに限られますが、モバイルアプリより先にサーバーが上がる問題は残ります。手動更新をおすすめします。

v1.x のまま長く放置していました。いきなり v3 に上げてもいいですか？

先に changelog:breaking-change ラベルの付いたディスカッションを、今のバージョンより新しいものから順に全部読んでください。特に v1.133.0 の VectorChord 移行が未完了なら、v3.0.0 は pgvecto.rs を読めないので、そこで止まります。バックアップを取り、データベースのイメージを差し替えてから v3 に上げてください。

#immich#docker-compose#updates#self-hosting#postgres