ImmichをWindows PCに導入するときによくあるエラーと対処法【Docker・WSL・外部ライブラリ】

ImmichをWindows PCに導入すると、手順どおりに進めたつもりでも、Docker、WSL、Ubuntu、外部ライブラリ、ポート番号まわりでつまずくことがあります。

私も実際に、UbuntuでDockerコマンドが使えなかったり、外部ライブラリのパス指定でエラーが出たり、既存データがあるのに初回登録画面のように見えたりしました。

この記事では、WindowsメインPCでImmichを運用するときに起こりやすいエラーを、原因と対処法に分けてまとめます。

初心者でも切り分けしやすいように、どこを確認すればいいかも一緒に書いていきます。

エラー1：Ubuntuでdockerコマンドが見つからない

UbuntuでImmichを起動しようとしたときに、次のようなエラーが出ることがあります。

The command 'docker' could not be found in this WSL 2 distro.

これは、Ubuntu側で docker コマンドが使えない状態です。

原因

まず第一にDocker Desktopが起動されていない場合があります。

次に、Docker DesktopのWSL Integrationが有効になっていない可能性があります。

Docker Desktopをインストールしていても、Ubuntuとの連携が有効になっていないと、Ubuntu側からDockerを操作できません。

WindowsにはDocker Desktopが入っているのに、Ubuntuで docker が使えない場合は、まずWSL Integrationを確認しましょう。

対処法

Docker Desktopを開きます。

設定画面から、次の場所を確認します。

Settings
  → Resources
    → WSL Integration

Ubuntuが表示されている場合は、UbuntuのスイッチをONにします。

この設定を有効にすると、Ubuntu側からDockerコマンドを実行できるようになります。

上にある Enable integration with my default WSL distro は、Windowsで既定に設定されているWSL環境に対してDocker連携を有効にする設定です。

Ubuntuを既定のWSLとして使っている場合はONにしておくと分かりやすいですが、重要なのは、Immichを動かすUbuntuのスイッチがONになっているかどうかです。

その後、Ubuntuを開き直して、次のコマンドを実行します。

docker --version
docker ps

Dockerのバージョンやコンテナ一覧が表示されればOKです。

docker コマンドが使えない状態では、Immichの起動や停止もできません。

まずはUbuntu側でDockerを操作できる状態にしてから、Immichの作業に進みます。

UbuntuがWSL Integration画面に表示されない場合は、PowerShellで次のコマンドを実行し、UbuntuがWSL2として認識されているか確認します。

wsl -l -v

Ubuntuが表示されていて、右端の VERSION が 2 になっていればWSL2として動いています。

エラー2：docker.sockに接続できない

UbuntuでDockerコマンドを実行したときに、次のようなエラーが出ることがあります。

failed to connect to the docker API at unix:///var/run/docker.sock

原因

Ubuntu側から、Docker DesktopのDockerエンジンに接続できていない状態です。

考えられる原因は、主にこのあたりです。

• Docker Desktopがまだ完全に起動していない
• WSL Integrationが不安定になっている
• Docker Desktop側の準備が終わっていない
• Docker Desktopの再起動が必要になっている

私の環境では、Docker Desktopを起動してすぐにUbuntuを開いたり、Docker Compose up -dを行うと起動できない事がありました。

対処法

まず、Docker Desktopが起動しているか確認します。

そのうえで、Ubuntu側から次のコマンドを実行します。

docker ps

ここでエラーが出るなら、まだImmichを起動する段階ではありません。

Docker Desktopの起動完了を待つか、Docker Desktopを再起動します。

WindowsメインPCでImmichを使う場合、Docker Desktopが完全に起動してからUbuntuを開く方が安定します。

私の環境ではDocker Desktopの再起動だけではエラーは消えず。
Windowsを再起動すると無事にエラー回避できました。

Docker Desktopを起動したら「Starting the Docker Engine…」の表示がある内はおとなしく待ちましょう。
Ubuntuの起動も避けます。

こうなれば準備完了です。
この状態になってから

cd ~/immich
docker compose up -d

を行うようにしましょう。

確認する場所

docker ps が通らない場合、Immichの設定ファイルを疑う前に、Docker DesktopとWSL Integrationを確認します。

docker ps

このコマンドが通らない状態で docker compose up -d を実行しても、Immichは正常に起動できません。

エラー3：WSL IntegrationにUbuntuが表示されない

Docker DesktopのWSL Integration画面で、Ubuntuが表示されないことがあります。

原因

UbuntuがWindows側で正しく認識されていないか、Docker Desktop側の認識がズレている可能性があります。

また、Docker Desktopのアップデート後に、WSL IntegrationがOFFになっていることもあります。

私の環境でも、Docker Desktopのアップデート後にWSL Integrationが外れていました。

対処法

まずPowerShellを開いて、次のコマンドを実行します。

wsl -l -v

Ubuntuが表示されているか確認します。

表示例はこのような形です。

  NAME      STATE           VERSION
* Ubuntu    Running         2

見る場所は、右端の VERSION です。

ここが 2 になっていれば、UbuntuはWSL2として動いています。

Ubuntuが表示されていない場合は、UbuntuのインストールやWSL環境を見直します。

Ubuntuが表示されているのにDocker Desktop側に出ない場合は、Docker DesktopやWindowsを再起動してから再確認します。

確認する場所

PowerShellでUbuntuが見えているかを先に確認します。

wsl -l -v

ここにUbuntuが出ていないなら、Docker DesktopではなくWSL側の問題です。

ここにUbuntuが出ているのにDocker Desktop側に表示されないなら、Docker Desktop側の連携設定を疑います。

エラー4：外部ライブラリでInvalid import pathが出る

Immichで外部ライブラリを追加しようとしたときに、次のエラーが出ることがあります。

Invalid import path: Path does not exist (ENOENT)

原因

Immichから見て、そのパスが存在していない状態です。

Windows上に F:\ImmichData\Photos があっても、Immichコンテナから見えていなければ存在しない扱いになります。

よくある原因はこのあたりです。

• F:\ImmichData\Photos のようなWindowsパスをImmichに入力している
• Ubuntu側の /mnt/f/ImmichData/Photos が存在しない
• docker-compose.yml に外部ライブラリ用のマウント設定がない
• Fドライブが接続されていない
• フォルダ名やパスを間違えている

特にハマりやすいのは、WindowsのパスをそのままImmichに入力してしまうパターンです。

Immichに入力するのは、Windows上のパスではなく、Dockerコンテナから見えるパスです。

対処法

まずUbuntu側で、Fドライブと写真フォルダが見えているか確認します。

ls /mnt/f
ls /mnt/f/ImmichData/Photos

ここでフォルダが見えない場合は、Immichからも見えません。

次に、docker-compose.yml の immich-server に外部ライブラリ用のマウント設定があるか確認します。

例として、Windows側の F:\ImmichData\Photos をImmichから見えるようにする場合は、docker-compose.ymlで次のように指定します。

- /mnt/f/ImmichData/Photos:/external/photos:ro

この設定にした場合、Immichの外部ライブラリ画面で指定するパスはこれです。

/external/photos

F:\ImmichData\Photos や、
/mnt/f/ImmichData/Photos ではありません。

左側の /mnt/f/ImmichData/Photos は、Ubuntuから見た実際の保存場所です。
右側の /external/photos は、Immichコンテナ内から見える場所です。

Immichの画面に入力するのは、右側のパスです。

確認する場所

Windowsでは写真フォルダがこのように見えていても、

F:\Photos

Ubuntu側ではこのように見ます。

/mnt/f/ImmichData/Photos

外部ライブラリで Invalid import path が出た場合は、まずUbuntu側でパスが見えるか確認します。

ls /mnt/f
ls /mnt/f/ImmichData/Photos

そのうえで、docker-compose.yml のマウント設定と、Immichに入力したパスを確認します。

エラー5：既存データがあるのに初回登録画面が出る

私自身、長らく放置していたエラーがこれです。

既存データがあるはずなのに、Immichを開いたら初回登録画面のような状態になったことがありました。

原因

この場合、写真本体が消えたとは限りません。

私の環境では、Immich本体というより、Docker Desktop、WSL、保存先ドライブ、DB、コンテナの起動順が噛み合っていなかった可能性が高いと考えました。

特にDBが正しく読めていない場合や、必要なコンテナが正常に立ち上がっていない場合、Immich上では別環境のように見えることがあります。

Immichでは、写真ファイル本体とは別に、ユーザー情報、アルバム情報、ライブラリ情報などをDB側で管理しています。

そのため、写真ファイルが残っていても、DBが読めていないと初回状態のように見えることがあります。

すぐに初回登録し直さない

既存データがあるはずなのに初回登録画面が出た場合、すぐに新しい管理者ユーザーを作らない方が安全です。

別環境として新しく作り直してしまうと、原因の切り分けがややこしくなります。

まずは写真フォルダ、DB保存先、コンテナの状態を確認します。

対処法

まず、写真本体が保存されているフォルダを確認します。

ls /mnt/f/ImmichData/Photos

次に、Immichのフォルダへ移動します。

cd ~/immich

.env のDB保存先を確認します。

cat .env

このような設定があるか確認します。

DB_DATA_LOCATION=./postgres

次に、実際にPostgres用のフォルダがあるか確認します。

ls
ls ./postgres

ここで postgres フォルダが見えない場合、以前使っていたDBとは別の場所を見ている可能性があります。

コンテナの状態を確認する

必要なコンテナが正常に起動しているか確認します。

docker compose ps

immich_server や database が正常に起動していない場合、Immichを開いても正しく表示されないことがあります。

ログを見る場合は、次のコマンドを使います。

docker compose logs database
docker compose logs immich-server

DB接続エラーや起動失敗が出ている場合は、まずDB側の問題を解消します。

Immichを起動し直す

写真フォルダ、DB保存先、コンテナ状態を確認したうえで、Immichを一度停止して起動し直します。

cd ~/immich
docker compose down
docker compose up -d

ただし、毎回これを手でやるのは面倒です。

私の環境では、最終的に起動順を整えることで安定しました。

restart: always のままだと毎回起動順で引っかかることがある

私の環境では、HDDの電源を入れ忘れて写真が表示されなかったこともありました。

ただ、それはあくまで単発の確認ミスです。

毎回のように引っかかっていたのは、HDDの認識というより、Docker Desktop、WSL2、Ubuntu、Postgres、Immich本体の起動順だった可能性が高いです。

特に気になっていたのが、docker compose up -d で起動したあとに、既存データがあるはずなのに初回登録画面のように見えることがほぼ毎回起こりました。

この状態になると、写真本体が消えたように見えてかなり焦ります。

しかし、実際には写真ファイルそのものが消えたのではなく、ImmichがDBや既存の管理情報を正しく読めていないだけの可能性があります。

ここで関係してくるのが、docker-compose.yml の restart 設定です。

Immichの docker-compose.yml で restart: always のままになっていると、Windows起動時やDocker Desktop起動時に、Immich関連のコンテナが自動で起動しようとします。

NASや専用サーバーのように24時間動かす環境なら便利です。

ただ、WindowsメインPCでは少し事情が違います。

Windowsは起動している。
Docker Desktopも起動し始めている。
でも、Docker Engineはまだ準備中。
UbuntuからDockerにはまだ接続できない。
Postgresもまだ完全に立ち上がっていない。

このような状態でImmichだけ先に動こうとすると、DBを正しく読めず、別環境のように見えることがあります。

その結果、既存データがあるのに初回登録画面のように見えてしまうわけです。

この記事では、WindowsメインPCで必要なときだけImmichを起動する運用を前提にしています。

そのため、docker-compose.yml の restart は次のように変更しておく方針にしました。

restart: "no"

restart: "no" にしておけば、PC起動時にImmichが勝手に立ち上がることはありません。

使いたいときは、自分で起動します。

cd ~/immich
docker compose up -d

停止するときは、通常どおりこちらです。

docker compose down

この方が、WindowsメインPCでは原因を切り分けしやすくなります。

Docker Desktopが起動しているか。
Ubuntuから docker ps が通るか。
Fドライブが見えているか。
Postgresの保存先が見えているか。

これらを確認してからImmichを起動できるので、初回登録画面のように見えたときも、どこで失敗しているのか追いやすくなります。

restart: always 自体が悪いわけではありません。

24時間稼働のNAS、ミニPC、自宅サーバーなら便利な設定です。

ただ、普段使いのWindowsメインPCで、必要なときだけImmichを使うなら、最初は restart: "no" にして手動起動に寄せた方が安全です。

注意：docker compose down -v は安易に使わない

原因が分からない段階で、次のコマンドは使わない方が安全です。

docker compose down -v

-v を付けると、Dockerのボリュームを削除する動きになります。

環境によってはDBやデータを消す原因になるため、原因が分かっていない段階では避けた方がいいです。

通常の停止だけなら、まずはこのコマンドで十分です。

docker compose down

WindowsメインPC運用で安定させる起動順

WindowsメインPCでImmichを使う場合、起動順はかなり大事です。

私の環境では、この順番にすると安定しました。

1. Docker Desktopを起動する
2. Docker Desktopが完全に起動するまで待つ
3. Ubuntuを開く
4. Ubuntu側でDocker接続を確認する
5. Fドライブが見えているか確認する
6. ~/immich に移動する
7. docker compose up -d を実行する
8. Immichが起動したらブラウザで開く

手動で確認する場合は、まずPowerShellでWSLの状態を見ます。

wsl -l -v

Ubuntuを開きます。

wsl -d Ubuntu

Ubuntu内でDocker接続を確認します。

docker ps

Fドライブを確認します。

ls /mnt/f
ls /mnt/f/ImmichData/Photos

Immichフォルダへ移動します。

cd ~/immich

Immichを起動します。

docker compose up -d

ブラウザでImmichを開きます。

http://localhost:8080

この順番で見ると、どこで失敗しているか分かりやすくなります。

docker ps が通らないなら、Docker DesktopやWSL Integrationの問題です。

/mnt/f/ImmichData/Photos が見えないなら、Fドライブやパスの問題です。

./postgres が見えないなら、DB保存先の問題です。

ブラウザで開けないなら、ポート番号や起動状態の問題です。

エラー6：localhost:8080でImmichが開けない

Immichを起動したはずなのに、ブラウザで次のURLを開いても表示されないことがあります。

http://localhost:8080

この場合、Immich自体の起動に失敗していることもありますが、別のソフトがすでに8080番ポートを使っている可能性もあります。

原因

Windows上で、別の常駐ソフトやローカルサーバー系のアプリが8080番ポートを先に使っていることがあります。

この状態でImmichを8080番ポートで起動しようとすると、Immich側がポートを使えず、ブラウザから開けません。

Ubuntuのエラーとして、次のような内容が出ることがあります。

Error response from daemon: ports are not available: exposing port TCP 0.0.0.0:8080 -> 127.0.0.1:0: /forwards/expose returned unexpected status: 500

対処法

まず、Windows側で8080番ポートを使っているソフトがないか確認します。

PowerShellを開いて、このコマンドを実行します。

netstat -ano | findstr :8080

何か表示された場合、右端にPIDという番号が出ます。

例：

TCP    0.0.0.0:8080    0.0.0.0:0    LISTENING    6596

この場合、6596 が8080番ポートを使っているプロセスIDです。

次に、そのPIDがどのソフトなのか確認します。

tasklist /FI "PID eq 6596"

ここで別のソフト名が表示された場合、そのソフトが8080番ポートを使っています。

解決方法1：8080番ポートを使っているソフトを終了する

一時的な確認であれば、8080番ポートを使っているソフトを終了してから、Immichを起動し直します。

Ubuntuで次のコマンドを実行します。

cd ~/immich
docker compose up -d

その後、ブラウザでImmichを開きます。

http://localhost:8080

これで開ければ、原因はポート競合です。

解決方法2：Immich側のポート番号を変更する

8080番ポートを他のソフトが使う可能性がある場合は、Immich側のポート番号を変える方が安定します。

docker-compose.yml の immich-server にある ports を確認します。

変更前の例です。

ports:
  - '8080:2283'

たとえば、外側のポートを8081に変えるなら、このように書き換えます。

ports:
  - '8081:2283'

左側の 8081 が、Windowsのブラウザからアクセスするポートです。

右側の 2283 は、Immichコンテナ内部で使われるポートです。

変更後は、Immichを起動し直します。

cd ~/immich
docker compose up -d

ブラウザで開くURLも変わります。

http://localhost:8081

確認する場所

ポート番号は docker ps で確認できます。

docker ps

たとえば次のように表示されていれば、8081番で開く設定になっています。

0.0.0.0:8081->2283/tcp

この場合、ブラウザで開くURLはこれです。

http://localhost:8081

docker-compose.yml で8081に変えたのに、ブラウザで8080を開いていると当然表示されません。

ポートを変更したら、開くURLも必ず合わせます。

Immichは起動したけど写真一覧が表示されない

Immichは起動しているのに写真一覧が表示されない場合は、画像保存先のパスが見えていない可能性があります。

外付けHDDを保存先にしている場合、PC起動後にHDDの電源が入っていないと、WSLやImmichから保存先フォルダが見えません。

私の環境では、Fドライブに使っているHDDをUSB→SATA変換ケーブルで接続し、ハブのコンセントからアダプターで電源を取っています。

そのため、HDDの電源スイッチをOFFのままPCを起動してしまい、「Immichは起動しているのに写真が表示されない」となることが今でもたまにあります。

外付けHDD運用なら、Immichの不具合を疑う前に、まず保存先ドライブの電源が入っているか確認してみてください。

Immichが起動しないときの切り分け早見表

Immichがうまく動かないときは、闇雲に設定を変えるより、どこで止まっているかを順番に見た方が早いです。

docker ps が通らない
→ Docker Desktop / WSL Integration の問題

wsl -l -v にUbuntuが出ない
→ WSL / Ubuntuの認識問題

ls /mnt/f/ImmichData/Photos が通らない
→ Windowsドライブ / WSL側のパス / 外部HDD接続の問題

Invalid import path が出る
→ docker-compose.ymlのマウント設定、またはImmichに入力したパスの問題

既存データがあるのに初回登録画面が出る
→ DB保存先 / Postgres / 起動順 / 別環境化の問題

localhost:8080 が開けない
→ ポート番号 / 起動状態 / 別ソフトとの競合

特にWindowsメインPCでImmichを使う場合、Docker Desktop、WSL、保存先ドライブ、Immichコンテナの起動順がズレると、原因が分かりにくくなります。

まずはこの順番で確認すると、切り分けしやすいです。

docker ps
ls /mnt/f
ls /mnt/f/ImmichData/Photos
cd ~/immich
docker compose ps
docker compose up -d

ブラウザで開くURLは、docker-compose.yml のポート設定に合わせます。

http://localhost:8080

8081に変更した場合は、こちらを開きます。

http://localhost:8081

Immichが起動しないと焦りますが、多くの場合は「Dockerが見えていない」「ドライブが見えていない」「DBが読めていない」「ポートが競合している」のどれかです。

順番に確認すれば、どこで止まっているか見つけやすくなります。