Immichのバージョンアップ手順:写真ライブラリを壊さず安全に更新する
Immichをdocker composeで安全にバージョンアップする手順。リリースノートの読み方、アプリを先に更新する理由、IMMICH_VERSIONの固定、ダウングレード不可への備え、移行中のログの見方まで。
結論:Immichのバージョンアップは「読む、アプリ、バックアップ、pull、待つ」の順
Immichのバージョンアップで写真ライブラリを壊さないコツは、コマンドより順番です。公式ドキュメント(2026年10月20日確認)のアップグレード手順は四つです。リリースノートを読んで破壊的変更に対応する、.env で IMMICH_VERSION を使っているなら目的のバージョンに書き換える、docker compose pull && docker compose up -d を実行する、必要なら docker image prune で古いイメージを消す。モバイルアプリを先に更新するのは同じページの「Versioning Policy」にある推奨で、手順の中には入っていません。更新前のバックアップとマイグレーションの完了待ちは、公式の通常手順には書かれていません。どちらも出てくるのは VectorChord への移行の節だけです。この記事ではこの二つも加えて、読む、アプリ、バックアップ、pull、待つ、の順で進めます。打つコマンドは実質2行しかありません。壊れるのは、その前後を飛ばしたときです。
Immichにはダウングレードがありません。新しいバージョンがデータベースを書き換えたあとで古いイメージに戻しても、サーバーは起動を拒否します。だからバックアップが pull より前にあります。以下、各手順で何を確認し、画面やログに何が出れば正常なのかを順に見ていきます。
なぜImmichのアップデートは慎重さが要るのか
Immichはセマンティックバージョニング(<major>.<minor>.<patch>)を採用していて、破壊的変更(breaking change)はメジャーバージョンでだけ入る方針です。2026年11月14日時点の最新版は v3.4.1(2026年11月11日公開)で、現在のメジャーである v3.0.0 は2026年7月2日に公開されました。v3.3.5 は認証局の侵害への対策と Node.js のセキュリティ修正を含み、公式は早めの更新を推奨しています。
慎重さが要る理由の一つ目は、マイグレーションが自動で走ることです。サーバーは新しいイメージで起動した瞬間に、データベースのスキーマを自分で書き換えます。「実行しますか」という確認はありません。そしてImmichは、一度書き換えたデータベースを古いバージョンに戻す手段を提供していません。公式ドキュメントは「同じマイナーバージョン内であっても、以前のバージョンへのダウングレードはサポートしない」と明記しています。
二つ目は、モバイルアプリとの互換性です。公式の説明では、アプリは「現在と一つ前のメジャーバージョン」に対応しますが、サーバーは「自分と同じメジャーバージョン」にしか対応しません。サーバーを先に上げると、アプリが取り残されます。
手順1:リリースノートと changelog:breaking-change ラベルを読む
更新前に読む場所は二つです。GitHubのリリースページと、changelog:breaking-change ラベルの付いたディスカッション一覧です。後者には v3.0.0、v2.0.0、v1.137.0、v1.136.0、v1.133.0 のようなリリースが並びますが、手作業が必要だったリリースだけではありません。v2.0.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 .envIMMICH_VERSION=v3 のような行が出れば固定されています。何も出なければ、docker-compose.yml の ${IMMICH_VERSION:-release} によって release タグが使われています。
選べるタグは次の通りです。
release:常に最新の安定版を指します。v4.0.0 が公開された瞬間、次のpullで v4 に上がります。破壊的変更を読む前にメジャーが変わり得る、ということです。v3:v3 系の最新安定版を指すメタタグです。公式ドキュメントによれば、メタタグはリリース候補(RC)を追いません。パッチとマイナーは自動で取り込み、メジャーは自分で.envを書き換えるまで変わりません。v3.3.4:特定のバージョンに完全固定します。バグ修正を受け取るたびに.envを書き換える必要があります。
おすすめは v3 です。バグ修正は自動で入り、メジャーの壁だけは手で越える。「読んでから上げる」を仕組みで保証する設定です。2026年10月20日時点で配布されている example.env(v3.3.4)の初期値も次のようになっています。
# 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 -dpull が .env のタグに合う新しいイメージを取得し、up -d がイメージや設定の変わったコンテナを作り直します。docker compose restart ではイメージが更新されない理由は Docker Composeのコマンド早見表 で説明しています。
起動後の確認は二つです。
docker compose ps
curl -s http://localhost:2283/api/server/versiondocker compose ps の STATUS 列が Up ... (healthy) なら起動完了です。(health: starting) は Docker のヘルス状態の初期値で、マイグレーション中かどうかは手順6のログで確認します。ヘルスチェックに成功すると healthy に変わります。/api/server/version は認証なしで応答するエンドポイントで、{"major":3,"minor":3,"patch":4} のような JSON が返ります。この数字が目標のバージョンと一致していれば、正しいイメージで動いています。
古いイメージはディスクに残り続けます。
docker image prune確認を求められるので y で答えます。これは、どのコンテナからも参照されていないタグのないイメージを消します。動いているコンテナのイメージは消えません。Immich のサーバーと機械学習のイメージは大きいので、VPS のディスクが小さいなら更新のたびに実行する価値があります。
手順6:マイグレーションが終わるまで待つ。再起動しない
docker compose logs -f immich-server新しいバージョンで最初に起動したとき、サーバーはデータベースのスキーマを更新します。ログには次の行が順に出ます(マイグレーション名は環境とバージョンで変わります)。
Running migrations
Migration "1752267649968-StandardizeNames" succeeded
Finished running migrationsFinished 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 で長時間止まって見えるのはエラーが出ていない限り正常だと書いています。この間のヘルス状態は (health: starting) だけでなく、ヘルスチェックの失敗が続くと unhealthy にも変わります。ヘルス状態だけで移行の進み具合は判断せず、ログで確認してください。所要時間は公式の説明で「数秒から数分」、ライブラリの規模で変わります。ログに If using Docker, consider increasing shm_size for the database. が出るなら、直前の Failed to vacuum のエラーを確認し、データベースコンテナの共有メモリの増量を検討してください。目安は 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年10月20日時点で公式 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: のブロックは削除する指示でした。どちらもイメージ側に組み込まれたからです。2026年10月20日時点の公式の移行手順の差分では、shm_size: 128mb の追加も含まれています。
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 の公式リポジトリは2025年12月17日にアーカイブされ、読み取り専用になっています。公式のアップグレードページは 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 がアプリを自動更新し、サーバーがアプリより古くなると、v3.3.1 のアプリ(2026年10月12日にソースで確認)では、新しいサーバーバージョンの情報を取得できている場合、管理者ユーザーの画面に「サーバーをアップデートできます」(英語UIでは Server update is available)という通知が出ます。v3.3.4 のアプリ(2026年10月20日にソースで確認)では、アプリのメジャーがサーバーより二つ以上進むと、ログイン画面に Your server version is not compatible with the mobile app! Please update your server to the latest version. という警告が出ます。逆にアプリのメジャーがサーバーより古いときの警告は Your mobile app version is not compatible with the server! Please update your mobile app to the latest version. です。文言はアプリのバージョンで変わり、古いアプリでは別の表示になります。
手順4で .env の IMMICH_VERSION を目的のバージョンに書き換えてから、サーバー側で 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) が出ていてエラーがなければ正常で、終わるのを待つだけです。health: starting は Docker のヘルス状態の初期値で、マイグレーション中であることを示す表示ではありません。ヘルスチェックに成功すると healthy に変わり、失敗が続くと unhealthy に変わります。Migration "..." failed や PostgresError 以外にも、.immich ファイルの欠落による ENOENT や保存先の読み書き権限の問題で起動に失敗します。エラーが出ている時は再起動を繰り返さず、エラー行をそのまま GitHub のディスカッションで検索してください。
IMMICH_VERSION は release と v3 のどちらにすべきですか?
v3 です。v3 は v3 系の最新安定版だけを指すメタタグで、パッチとマイナーは自動で取り込み、リリース候補は追わず、メジャーは .env を書き換えるまで変わりません。release は次のメジャーが出た瞬間にそれを指すので、リリースノートを読む前に破壊的変更が入ります。2026年10月20日時点の example.env(v3.3.4)の初期値も v3 です。
新しいバージョンで不具合が出ました。前のバージョンに戻せますか?
イメージのタグを戻すだけでは戻せません。古いサーバーは Downgrades are not supported. を含むエラーを出して起動を拒否します。戻す方法は、更新前に取ったデータベースのダンプとライブラリのコピーから復元し、.env を前のバージョンに固定して起動し直すことだけです。更新前のバックアップが必須なのはこのためです。
Watchtower で Immich を自動更新してもいいですか?
現在の公式アップグレードページは Watchtower に触れていません。ただし Immich は更新前にリリースノートを読むことを求め、ダウングレードを認めていないので、読まずに自動で pull する仕組みとは相性が悪いです。v3 に固定すれば影響はパッチとマイナーに限られますが、更新前にリリースノートを読む必要は残ります。手動更新をおすすめします。
v1.x のまま長く放置していました。いきなり v3 に上げてもいいですか?
先に changelog:breaking-change ラベルの付いたディスカッションを、今のバージョンより新しいものから順に全部読んでください。v1.107.2 未満から更新する場合は、まず v1.107.2 に上げて正常に起動することを確認してください。特に v1.133.0 の VectorChord 移行が未完了なら、v3.0.0 は pgvecto.rs を読めないので、そこで止まります。バックアップを取り、データベースのイメージを差し替えてから v3 に上げてください。