著者 Immichに必要なRAMとディスク容量は？
Immichの公式最小要件はRAM 6 GBです。サーバー、Postgres、Redis、機械学習の必要量を分解し、RAM 4 GBで動かす場合の設定と注意点を説明します。
Immich にはどの程度の RAM が必要ですか？
Immich が文書化している最小要件は 6 GB の RAM（random access memory）で、推奨値は 8 GB です。CPU は最低限 2 コア、快適に運用するには 4 コアが必要です。この値はスタック全体を対象としています。Immich は単一のアプリケーションではなく、4 つのコンテナで構成されるためです。すでにインポート済みのライブラリを閲覧するだけなら、必要なメモリは少なくて済みます。メモリを消費するのはインポート処理で、その大部分は停止できる 1 つのコンテナが使用します。
The data behind this chart
[
{
"label": "Documented minimum",
"ram_gb": 6,
"cpu_cores": 2
},
{
"label": "Documented recommended",
"ram_gb": 8,
"cpu_cores": 4
}
]これらは、2026 年 8 月時点で Immich の要件ページに記載されている値です。これはサイジングの推奨値であり、起動時にソフトウェアが確認する条件ではありません。Immich は、これより少ないメモリでも起動します。小規模なサーバーで変わるのは、どのバックグラウンドジョブが完了するかと、メモリ不足時にインポート処理がどう動作するかです。
実際のハードリミットが 1 つあります。Immich version 3 以降は amd64 ホスト上で x86-64-v2 CPU を必要とします。これは、おおむね 2012 年以降に販売されたプロセッサの大半に該当します。古いハードウェアでは、動作が遅くなるのではなく、コンテナの起動に失敗します。
まだインストール前であれば、まず Docker Compose を使用した VPS への Immich の完全なインストール を参照し、その後ここに戻ってサーバーのサイジングを確認してください。
メモリの内訳: 4 つのコンテナ
公式の Compose ファイルは 4 つのサービスを起動します。それぞれメモリ使用量の特性が異なるため、合計値だけでは重要な点が分かりません。
immich-server は Web インターフェースと API を提供し、バックグラウンドジョブのワーカーも実行します。この 1 つのコンテナ内で 2 つのワーカーが動作します。api はブラウザーとモバイルアプリからのリクエストに応答します。microservices は、サムネイル生成や動画エンコードを含むキューを処理します。変数 IMMICH_WORKERS_INCLUDE と IMMICH_WORKERS_EXCLUDE を設定すると、この 2 つを別々のコンテナに分けられます。これにより、負荷の大きい側には専用のメモリ上限を設定し、写真を提供する側のメモリを制限せずに済みます。
database は VectorChord 拡張機能を組み込んだ PostgreSQL 14 イメージです。すべてのメタデータと、アセットごとに 1 つの検索ベクトルを保持します。Immich のドキュメントでは、このサービスに対してのみスタック内で明示的な最低値を定めています。Docker のリソース制限を適用する場合、データベースには少なくとも 2 GB が必要です。同じページでは、データベースをローカル SSD ストレージ上に置き、いかなる種類のネットワーク共有にも置かないように説明しています。ベクトルとインデックスの検索は小さなランダム読み取りであり、ネットワークボリュームでは読み取りのたびに往復通信が発生するためです。プランの選択がこの点に左右される場合、VPS の NVMe と SATA SSD ストレージの違いは、このスタックのほかの部分よりもここで重要になります。
redis は Valkey イメージを実行し、ジョブキューを保持します。写真データではなくジョブの記録を保存するため、4 つのサービスの中では大幅に小さいメモリ使用量です。
immich-machine-learning は、必要なプランサイズを決めるサービスです。スマート検索、顔検出、テキスト認識のモデルを読み込み、読み込まれたモデルはメモリ上に常駐します。MACHINE_LEARNING_MODEL_TTL のデフォルト値は 300 であるため、リクエストが 5 分間ないとモデルは破棄され、次のリクエスト時に /cache ボリュームから再度読み込まれます。一括インポート中は 5 分間リクエストが途切れることがないため、最初のアセットから最後のアセットまでモデルは読み込まれたままです。
インポート中に発生する変化
アイドル状態の Immich は静かです。小規模なサーバーで問題が発生するのはインポート中です。1 つのアセットをアップロードすると、一連のジョブがキューに入り、複数のキューが同時に実行されるためです。
メタデータの抽出ではファイルヘッダーを読み取ります。負荷は軽い処理です。サムネイルの生成は、より負荷が高い処理です。Immich はアセットごとに 3 種類のサムネイルを生成します。ぼかした thumbhash プレースホルダー、WebP プレビュー、JPEG サムネイルです。さらに、検出した顔ごとにサムネイルを 1 つ追加で生成します。これらの各ジョブでは画像をデコードします。ジョブの並列度によって、同時にデコードする数が決まります。並列度は、ジョブ単位の小さな負荷をサーバー全体の負荷に拡大する要因です。そのため、Immich FAQ では、リソースが限られたマシンで最初に下げる設定として並列度を挙げています。Administration の Settings、Job Settings で、負荷の高いキューの並列度を 1 に設定します。
動画アセットではトランスコードも発生します。各トランスコードジョブは、それぞれ専用のメモリを使用する独立した FFmpeg プロセスです。許可したすべての CPU スレッドを使用します。
Smart search では、新しいアセットをすべて machine learning コンテナに送り、1 つの埋め込みベクトルを計算します。顔検出では、同じ画像に対して 2 つ目のモデルを実行します。既存の写真ライブラリを最初にインポートすると、これら 2 つのキューが所有するすべてのアセットを対象に数時間実行されます。インストール全体でメモリ使用量が最も高くなるのはこの時点です。この処理は 1 回だけ発生します。
顔認識と物体認識で最も多くの RAM が必要になる理由
顔の処理には 2 つの処理があります。顔検出では機械学習コンテナ内のモデルを実行し、顔の位置を示すボックスを検出します。続く顔認識では、検出結果を人物ごとにまとめます。この処理では Postgres のベクトルインデックスを検索します。そのため、ライブラリが大きいと、まず検出中のモデルコンテナ、次にグループ化中のデータベースへ順番に負荷がかかります。
次の 4 つの設定によって、機械学習コンテナが保持するデータ量が変わります。
- 顔モデル。Immich はデフォルトで
buffalo_lを使用し、FAQ では小規模なサーバーにbuffalo_sを推奨しています。こちらは小型のモデルなので、メモリ使用量が少なく、処理も高速です。ただし、小さな顔や横向きの顔では精度が低下します。 - ワーカー数。
MACHINE_LEARNING_WORKERSのデフォルト値は 1 です。各ワーカーは、モデルのコピーをそれぞれ読み込む独立したプロセスです。そのため、2 にすると常駐モデルメモリはおよそ 2 倍になります。十分な RAM がない限り、1 のままにしてください。 - バッチサイズ。
MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITIONは一度に処理する顔の数を制限します。バッチはまとめてメモリ上に保持されるため、40 人が写った集合写真は、1 人のポートレートより多くのメモリを使用します。 - 実行するモデルの種類。スマート検索、顔検出、テキスト認識は、それぞれ専用のモデルを読み込みます。Administration、Settings、Machine Learning Settings で使用しない機能を無効にすると、インポートの実行中だけでなく、継続的にそのメモリ使用量を削減できます。
MACHINE_LEARNING_MODEL_ARENA もあります。これはメモリの断片化を防ぐために CPU メモリを事前に割り当てる設定で、デフォルトでは有効です。この設定の変更は最後に行ってください。効果は使用しているメモリアロケーターに依存するため、判断するには変更前後の docker stats を監視するしかありません。
3 つの構成例: 2 GB、4 GB、8 GB
The data behind this chart
[
{
"label": "2 GB VPS",
"server_limit_mb": 768,
"db_limit_mb": 768,
"ml_limit_mb": 0,
"redis_limit_mb": 128,
"notes": "machine learning container removed"
},
{
"label": "4 GB VPS",
"server_limit_mb": 1024,
"db_limit_mb": 1280,
"ml_limit_mb": 1024,
"redis_limit_mb": 192,
"notes": "machine learning on, job concurrency 1, buffalo_s"
},
{
"label": "8 GB VPS",
"server_limit_mb": 2048,
"db_limit_mb": 2048,
"ml_limit_mb": 2560,
"redis_limit_mb": 256,
"notes": "everything on at default settings"
}
]これらは Immich が使用する実測値ではなく、Compose に入力する上限値として扱ってください。上限は最大値です。何も予約せず、サービスの使用量を小さくするものでもありません。ホストのメモリが枯渇したときに、どのサービスをカーネルが kill するかを決めます。これは、カーネル独自のスコアリングに任せるより、管理者が決めるほうが適切です。
2 GB の構成: machine learning コンテナを削除する
2 GB は、文書化されている 6 GB の最小要件を下回ります。そのため、これは妥協案であることを明確にしておく必要があります。docker-compose.yml 内の immich-machine-learning サービス全体をコメントアウトするか、サービスを起動したまま Administration の Settings、Machine Learning Settings ですべてのモデルを無効にしてください。コンテナを削除するほうが確実です。モデルを無効にしても、Python プロセスは常駐するためです。
アップロード、アルバム、共有、モバイルバックアップ、サムネイル、日付・場所・ファイル名による検索は利用できます。説明文による検索、顔の自動認識と人物ごとのグループ化、画像内の文字認識は利用できません。
4 つの上限の合計は約 1.7 GB で、ホストにはおよそ 300 MB が残ります。データベースの 768 MB は、文書化されている 2 GB の下限を下回る点に注意してください。これが 2 GB で必要になる妥協であり、この構成で Postgres が kill される可能性が最も高いサービスになる理由です。
最初に問題が発生するのは、閲覧ではなくインポートです。数万枚台前半のライブラリは、取り込み後であればおおむね問題なく閲覧できます。ページの配信は、メタデータのクエリとファイルの読み取りで構成されるためです。同じホストで動画を大量にインポートすると、トランスコードとサムネイルキューが同時にメモリを必要とするため、swap が発生します。負荷の高い各キューの同時実行数を 1 に設定し、swap ファイルを追加してください。
4 GB の構成: machine learning を有効にし、ジョブを 1 件ずつ実行する
4 GB は、顔認識と物体認識を有効にする価値がある最小構成です。machine learning コンテナを 0 MB に制限し、顔認識を buffalo_s に切り替え、サムネイル生成、顔検出、smart search のジョブ同時実行数を 1 に設定してください。
既存のライブラリに対する初回処理には数時間かかり、大規模なライブラリでは 1 日を超えることがあります。これはメモリではなく CPU の制約によるものなので、RAM を増やしても処理時間は短くなりません。
この構成で最初に問題が発生するのは、初回の一括処理中の machine learning コンテナです。上限を設定しないと、トランスコードジョブもメモリを消費する中で、コンテナの使用量が増え続けます。その結果、カーネルは 2 つのうち大きいほうを kill します。docker ps -a で Exited (137) が確認され、コンテナが再起動します。キューは、前回確認したときより静かに遅延しています。
8 GB の構成: 文書化されている推奨構成
8 GB と 4 コアは、Immich の推奨構成に一致します。smart search、顔検出、文字認識、トランスコードを、デフォルトの同時実行数で実行できます。10 万件を超えるアセットを含むライブラリでも、ここでは余裕があります。負荷の中心はメモリからディスク速度へ移ります。データベースは、ベクトルインデックスとメタデータクエリを終日処理するためです。
それでも上限は設定してください。余裕のあるホストでも、暴走したキューがデータベースを巻き込んで停止するのを防げます。小さい構成と比較して料金を検討している場合は、メモリ容量別に見た VPS の実際の料金を確認すると、8 GB プランがチューニングを止める最も安価な方法だと分かることが多いです。
Compose の制限でサービスごとのメモリ上限を設定する方法
このために docker-compose.yml を編集しないでください。このファイルは wget によってアップグレードのたびに置き換えられます。制限は、隣にある docker-compose.override.yml に記述してください。docker compose が自動的にマージします。
services:
immich-server:
deploy:
resources:
limits:
memory: 1024M
immich-machine-learning:
deploy:
resources:
limits:
memory: 1024M
cpus: '1.5'
database:
deploy:
resources:
limits:
memory: 1280M
redis:
deploy:
resources:
limits:
memory: 192Mdocker compose up -d
docker stats --no-streamdocker stats の MEM USAGE / LIMIT 列には、ホスト全体のメモリ容量ではなく、設定した上限が表示されるはずです。制限列にホストの全容量が表示される場合は、override ファイルが読み込まれていません。ファイル名を確認し、docker compose config を実行してマージ後の結果を確認してください。
制限が低すぎると、遅いサービスが停止したサービスになります。コンテナが再起動を繰り返す場合は、上限を引き上げてください。詳しい仕組みについては、Docker Compose でサービスごとにメモリ制限を設定する方法を参照してください。Compose v2 では、deploy が Swarm 以外でも機能する理由も説明しています。
機械学習コンテナを停止または移動する方法
小規模なサーバーでは、このコンテナを別の場所へ移動することが最も大きな変更になります。Immich は、別のマシンでコンテナを実行できます。2 台目のホストに次のファイルを作成します。夜間のみ起動するデスクトップでも構いません。
name: immich_remote_ml
services:
immich-machine-learning:
container_name: immich_machine_learning
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
volumes:
- model-cache:/cache
restart: always
ports:
- 3003:3003
volumes:
model-cache:docker compose up -d
curl -s http://localhost:3003/ping次に、Web インターフェースで Administration、Settings、Machine Learning Settings の順に開き、Add URL をクリックして http://<host>:3003 を入力します。2 台のホストで同じバージョンを使用してください。Immich のドキュメントでは、両者のバージョンが異なるとバグや不安定な動作の原因になると警告しています。
このポートでは、写真が暗号化されずにもう一方のマシンへ転送されます。そのため、プライベートネットワーク上で使用するか、2 台のホスト間に WireGuard トンネルを構成して通信を通してください。3003 をインターネットに公開しないでください。
常駐モデルコンテナそのものが問題であれば、プランのサイズを決める前に、PhotoPrism と Immich が常駐時に実行するものの違いを比較する理由にもなります。
Immich ライブラリにはどの程度のディスク容量が必要ですか？
単一の倍率では計算できません。4 種類のデータが、それぞれ異なる割合で増えるためです。以下は、写真 50,000 枚と短い動画 500 本のライブラリで計算した例です。
The data behind this chart
[
{
"label": "Originals: 50,000 photos at 4 MB",
"gb": 200
},
{
"label": "Originals: 500 videos at 120 MB",
"gb": 60
},
{
"label": "Thumbnails and encoded video at 15%",
"gb": 39
},
{
"label": "Postgres database",
"gb": 3
},
{
"label": "Machine learning model cache",
"gb": 2
}
]写真の 200 GB と動画の 60 GB は仮定値です。購入前に、自分の平均サイズへ置き換えてください。この容量を左右するのは動画です。スマートフォンで撮影した動画 1 分分は、写真 100 枚より大きくなります。
find /srv/immich/upload -type f -printf '%s\n' \
| awk '{n++; s+=$1} END {printf "%d files, %.1f MB average\n", n, s/n/1048576}'39 GB の行だけが、Immich が公開している比率です。生成されるサムネイルとトランスコード済み動画により、ライブラリのサイズは平均で 10 から 20 パーセント増えます。動画のうち、ブラウザー互換性のために再エンコードが必要な割合によって異なるため、範囲で示されています。JPEG のライブラリは、この範囲の下限に近くなります。
データベースは 3 GB で、ほぼ固定のコストです。Immich のドキュメントでは、データベースファイルは通常 1 から 3 GB とされています。ピクセルではなく、メタデータと検索ベクトルを保持するためです。モデルキャッシュは 2 GB で、複数のモデルを有効にしたり、異なるモデルを試したりすると増加します。FAQ でこの領域が容量を消費すると説明されているのは、このためです。
5 行の合計は 300 GB を少し超えます。そのため、500 GB のボリュームなら増加分の余裕が残りますが、250 GB のボリュームでは不足します。次のコマンドで内訳を確認できます。
grep UPLOAD_LOCATION .env
du -sh /srv/immich/*UPLOAD_LOCATION の下には 6 つのフォルダーがあります。upload と library にはオリジナルが保存され、thumbs にはプレビューと顔サムネイル、encoded-video には再エンコードされたコピー、profile にはアバター、backups には自動データベースダンプが保存されます。upload、library、profile だけが代替できません。それ以外は、これらから再生成できます。
2 つの点で意外に感じることがあります。削除したアセットは最初にゴミ箱へ移動され、ゴミ箱を空にするまで容量を保持します。そのため、大規模な削除を実行した当日は空き容量が増えません。もう 1 つは、データベースダンプにはメタデータしか含まれないことです。ファイルがなければ役に立ちません。
docker exec -t immich_postgres pg_dump --clean --if-exists \
--dbname=immich --username=postgres | gzip > /srv/backups/immich-dump.sql.gzこれに加えて、オリジナルのファイルレベルのコピーをサーバー外の場所に保存してください。VPS からサーバー外のストレージへの restic バックアップは、そのために使用します。
トランスコードは RAM ではなく CPU を使用します
RAM を増設しても、トランスコードは高速になりません。Immich は FFmpeg でトランスコードするため、通常の VPS ではすべてのフレームを CPU でデコードおよびエンコードします。ハードウェアアクセラレーションを利用できる場合でも、Immich のドキュメントによると高速化されるのはエンコードだけです。そのため、CPU はソフトウェアデコードとトーンマッピングを引き続き実行します。
ハードウェアアクセラレーションには、追加の hwaccel.transcoding.yml Compose ファイルと、デバイスのパススルーが必要です。使用できる方式は NVENC、Quick Sync、RKMPP、VAAPI です。多くの VPS プランでは、これらを利用できません。そのため、CPU での処理を前提にしてください。
実際に調整すべき設定はスレッド数です。Administration、Settings、Video Transcoding Settings の順に開きます。スレッド数が 0 の場合はすべてのコアを使用するため、2 コアのプランでは 1 本の動画によって Web インターフェースが停止したようになることがあります。Immich FAQ の推奨どおり、ここでは 1 または 2 に設定してください。トランスコードは遅くなりますが、他の処理を妨げにくくなります。
スワップスラッシングによるインポートがハングに見える理由
これは、最も頻繁に誤解される障害です。Immich がメモリ不足になると、2 つの結果のいずれかになります。そのうち、障害に見えるのは 1 つだけです。
スワップがない場合、カーネルはプロセスを強制終了します。コンテナは数秒以内に再起動するため、ブラウザーから見るとジョブキューが一時停止してから再開したように見えます。根拠は docker ps -a にあります。
docker ps -a --filter name=immich
docker inspect immich_machine_learning | grep -i oomkilled
sudo dmesg -T | grep -i -E 'out of memory|oom-kill'Exited (137) は、プロセスが signal 9 で強制終了されたことを示します。137 は 128 に 9 を加えた値です。OOMKilled の値が true であれば、クラッシュではなくメモリ不足によって強制終了されたことを確認できます。
スワップがある場合、プロセスは強制終了されず、エラーも発生しません。カーネルがページをディスクへ移動し始めるため、インポートが桁違いに遅くなり、Web インターフェースは通常のタイムアウト時間内に応答しなくなります。すべてのコンテナは実行中です。すべてのヘルスチェックも成功する可能性があります。ハングしたように見えるため、この時点でサーバーを再起動する人がいます。しかし、これによりキューの進行状況が失われるだけで、状況は変わりません。
free -m
vmstat 1 5vmstat の si 列と so 列に 0 ではない値が継続して表示される場合、マシンがスワップの読み書きを継続的に行っています。これはスラッシングが発生している状態です。同時に、Swap の free -m 行にある使用量も増加します。
2 GB または 4 GB のサーバーでも、スワップは追加してください。診断できる遅いインポートのほうが、原因を特定できないまま強制終了されるコンテナよりも対処しやすいためです。
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstabその後で原因を修正します。ジョブの同時実行数を 1 に下げる、機械学習コンテナに上限を設定する、またはそのコンテナをこのホストから移動します。スワップは、その対応を行うための時間を確保します。スワップだけでは解決になりません。
FAQ
Immich を 2 GB の VPS で実行できますか？
はい。docker-compose.yml から immich-machine-learning サービスをコメントアウトし、ジョブの同時実行数を 1 に設定します。これは公式に記載された最小値である 6 GB を下回るため、既知の妥協策として扱ってください。アップロード、アルバム、共有、モバイルバックアップ、日付・場所・ファイル名による検索は利用できます。説明による検索、顔の自動分類、画像内の文字認識は利用できません。インポート時の負荷が原因でコンテナが強制終了される代わりにサーバーの処理が遅くなるよう、2 GB の swap ファイルを追加してください。
Immich のインポートがエラーメッセージなしで停止するのはなぜですか？
ブラウザーからは、2 つの異なる原因が同じように見えます。メモリ不足でコンテナが強制終了された場合は docker ps -a に Exited (137) が表示され、コンテナはすでに再起動しています。ホストが swap を使用している場合は、すべてのコンテナが動作したまま、全体の処理だけが非常に遅くなります。vmstat 1 5 で両者を区別できます。si 列と so 列に 0 ではない値が継続して表示される場合は、swap が使用されています。どちらの場合も、サムネイル生成、顔検出、スマート検索のジョブ同時実行数を下げてください。
Immich のログに表示される終了コード 137 は何を意味しますか？
137 は 128 にシグナル 9 を加えた値であるため、プロセスは SIGKILL で強制終了されています。実際には、コンテナ自体のメモリ制限に達したか、ホストのメモリが枯渇したため、メモリ上限に達したことを意味します。docker inspect immich_machine_learning | grep -i oomkilled で確認してください。true の値が であれば、カーネルがメモリ不足を理由に強制終了したことを示します。その後、free -m と sudo dmesg -T | grep -i oom-kill により、原因がコンテナの制限かホスト全体のメモリ不足かを確認できます。通常、最も大きなプロセスである machine learning コンテナが影響を受けます。
Immich には写真 1 枚あたりどの程度のディスク容量が必要ですか？
元のファイルに 10 から 20 パーセントを加えた容量を見積もってください。Immich のドキュメントでは、生成されるサムネイルとトランスコード済みの動画によって、ライブラリのサイズが平均で 10 から 20 パーセント増加すると説明されています。大規模なライブラリでも、データベース自体は通常 1 から 3 GB です。実際に総容量を左右するのは動画です。写真の枚数に倍率を適用するのではなく、プランを選ぶ前に自分のファイルの平均サイズを測定してください。
Immich に GPU は必要ですか？
いいえ。Immich のすべての機能は CPU で動作します。GPU があれば、machine learning コンテナでのモデル推論と動画エンコードを高速化できますが、どちらにも必須ではありません。ほとんどの VPS プランでは GPU を利用できません。CPU のみの環境では、トランスコードのスレッド数を 1 または 2 に設定し、buffalo_s の顔モデルを使用して、最初の一括インポートを夜間に実行してください。