Immich Docker Compose 5 個常見錯誤修正
3 個安裝步驟、4 個常見修正，幫你用 Docker Compose 跑起 Immich，並避開 Docker v25 healthcheck.start_interval 問題。
Immich Docker Compose 安裝時，最常卡住的是哪幾個錯誤？
這篇整理 Immich 的 Docker Compose 安裝流程，並列出最常見的 4 個修正。
| 項目 | 重點 | 常見卡點 |
|---|---|---|
| Immich | 自架相片管理服務 | 需要正確的 Compose 與環境變數 |
| Docker Compose | 用來啟動整組服務 | 舊版指令或錯誤套件會失敗 |
| Docker Engine | 執行容器的核心 | v25 以下可能不支援 healthcheck.start_interval |
| Immich release files | docker-compose.yml 與 .env | 兩個檔案要放同一資料夾 |
1. 先把 Immich 檔案抓下來
訂閱 AI 趨勢週報
每週精選模型發布、工具應用與深度分析，直送信箱。不定期，不騷擾。
不會寄垃圾信，隨時可取消。
Immich 的官方做法很直接：先建立一個工作資料夾，再把 docker-compose.yml 和 .env 放進去。這樣做的好處是，後面所有指令都假設兩個檔案在同一層，少了路徑錯誤的機會。
如果你是從瀏覽器下載，也要記得把範例環境檔改名成 .env。這一步看起來簡單，但很多人其實是因為檔名或位置不對，才會在啟動前就失敗。
mkdir ./immich-appcd ./immich-appwget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.ymlwget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env
2. 先改 .env，再啟動
.env 決定了上傳檔案放哪裡、Postgres 資料放哪裡，以及你要跑哪個版本。預設值可以拿來測試，但正式使用前，通常要把 UPLOAD_LOCATION 改成有足夠空間的路徑，並換掉資料庫密碼。
官方也提醒，資料庫檔案不要放在網路磁碟上，密碼最好別用太多特殊字元，以免 Docker 解析出問題。若你需要時區設定，可以取消註解 TZ=Etc/UTC 再改成你的地區。
UPLOAD_LOCATION=./libraryDB_DATA_LOCATION=./postgresIMMICH_VERSION=v3DB_PASSWORD=postgresDB_USERNAME=postgresDB_DATABASE_NAME=immich
3. 用正確的 Compose 指令啟動
檔案改好後，就在同一個資料夾執行 docker compose up -d。-d 代表背景執行，適合要長時間運作的伺服器，不會因為關掉終端機就停掉。
如果這一步報錯，問題常常不是 Immich，而是 Docker 安裝來源。某些 Ubuntu 環境會因為套件版本或 plugin 不一致，導致你其實跑到舊工具；這時候要改裝 Docker 官方版本，並先移除舊套件。
docker compose up -d- 使用 docker compose，不是 docker-compose
- 優先安裝 Docker 官方 repository 的 Engine
- 先移除舊的發行版套件
4. 看到版本不合，就先懷疑 Docker 套件
官方文件提到兩種常見錯誤，背後常是同一件事：系統上的 Docker 版本或 plugin 不對。像是 unknown shorthand flag: 'd' in -d，或是 Compose file './docker-compose.yml' is invalid 搭配 'name' does not match any of the regexes，都很像是舊版工具在作怪。
處理方式通常不是改 Immich，而是把 Docker Engine 換成官方套件來源，並確保 docker compose 真正指向你要的版本。這一步做對，後面很多奇怪錯誤會一起消失。
# 正確方向
docker compose up -d
# 舊工具常見問題來源
docker-compose up -d5. 遇到 healthcheck.start_interval，就改 compose 檔
如果 Docker 提示 healthcheck.start_interval 需要 Docker Engine v25 以上，代表你的引擎太舊，不認得這個設定。官方提供的解法很直接：到 docker-compose.yml 裡把資料庫服務的 start_interval 註解掉，再重新啟動。
這是過渡解法，不是長期最佳解。如果你能升級到新版 Docker Engine，還是建議升級；但如果你現在只想先把 Immich 跑起來，這個修改通常最快。
- 打開
docker-compose.yml - 找到資料庫服務區塊
- 註解
start_interval - 再跑一次
docker compose up -d
怎麼挑
大多數人先照標準流程做：下載兩個檔案、改好 .env、再用 docker compose up -d 啟動。這條路最適合第一次部署 Immich 的人，也最容易維持之後的更新。
如果你卡住，先對症下藥：指令或版本錯誤，多半是 Docker 套件裝錯；healthcheck.start_interval 則代表 Engine 太舊，先註解那行或升級到 v25 以上再繼續。