Immich 裝在 Windows:官方立場、WSL 2 架設與會壞的地方

Immich 有 Windows 版嗎?先講結論

Immich 在 Windows 上能不能用,要看你指的是哪一件事。Immich 官方文件提供的使用方式是網頁介面、手機 App 和命令列工具,文件裡找不到可以下載安裝的官方 Windows 桌面程式。伺服器本身可以用 Docker Desktop 的 WSL 2 後端架在 Windows 電腦上,但 Immich 官方明說強烈不建議,而且資料庫必須放在 Docker 的具名 volume 裡,不能放在 Windows 磁碟上。

搜尋「immich windows」的人,通常是想做下面三件事之一:

1. 在 Windows 電腦上「使用」Immich:看照片,或把電腦裡的舊照片傳上去。
2. 把 Immich 的「伺服器」架在自己的 Windows 電腦上。
3. 伺服器放在 NAS 或 VPS,Windows 電腦只負責上傳。

下面照這個順序講。第 2 件事的篇幅最長,因為會出問題的地方幾乎都在那裡。

在 Windows 上使用 Immich:官方工具有哪些

Immich 的用戶端和伺服器是分開的。官方快速入門頁列出的用戶端是手機 App,以及用瀏覽器打開 http://<伺服器IP>:2283 的網頁介面。所以在 Windows 上,瀏覽器本身就是 Immich 的用戶端,不需要另外安裝程式。第一個在網頁介面註冊的帳號會成為管理員(admin)。

手機 App 可以從 Apple App Store、Google Play 取得。Android 也可以從 GitHub Releases 下載 APK,或透過 Obtainium、FUTO F-Droid 安裝。

官方 CLI:用命令列整批上傳

要把電腦裡多年累積的照片一次傳上去,官方給的工具是 CLI(command-line interface,命令列介面)。它是 npm 套件 @immich/cli,需要 Node.js 22 或更新版本。裝好 Node.js 之後,在 PowerShell 執行:

node --version
npm i -g @immich/cli

node --version 印出的版本號應該是 v22 或更高。如果你以前裝過舊版 CLI(套件名稱是 immich),官方要求先用 npm uninstall -g immich 移除,再裝新的。

API 金鑰(API key)在網頁介面的使用者設定裡產生。官方範例的伺服器網址結尾是 /api,照著寫:

immich login http://192.168.1.50:2283/api YOUR_API_KEY
immich upload --dry-run --recursive D:\Photos
immich upload --recursive D:\Photos

--dry-run(簡寫 -n)只列出會上傳哪些檔案,不會真的上傳,第一次請先跑它。--recursive 預設是關閉的,不加就不會進入子資料夾。其他常用選項:--album-name(簡寫 -A)指定相簿名稱;--concurrency(簡寫 -c)控制同時上傳幾個檔案,預設是 4。

CLI 文件頁沒有特別提到 Windows,範例全是 Linux shell 的寫法。如果在 PowerShell 裡遇到路徑問題,可以改在 WSL 的 Ubuntu 裡執行同樣的指令,Windows 的 D 槽在那裡是 /mnt/d。

不想裝 Node.js 的話,官方也提供 Docker 映像 ghcr.io/immich-app/immich-cli。官方範例用的是 bash 的 $(pwd),代表目前所在的資料夾。在 PowerShell 裡,對應的寫法是 ${PWD}:

cd D:\Photos
docker run -it -v "${PWD}:/import:ro" -e IMMICH_INSTANCE_URL=http://192.168.1.50:2283/api -e IMMICH_API_KEY=YOUR_API_KEY ghcr.io/immich-app/immich-cli:latest upload --recursive /import

/import:ro 表示照片資料夾以唯讀方式掛進容器,所以上傳過程不會改動你的原始檔案。

社群工具:immich-go 與它的圖形介面

網路上常被推薦的 immich-go 不是 Immich 官方專案。它放在 simulot/immich-go 這個 GitHub 帳號下,不在 immich-app 組織裡。Immich 文件的社群專案頁(現在轉址到 awesome.immich.app)把它列在命令列工具一類。它的 README 說,這是為了把大量照片上傳到自架 Immich 伺服器而做的開源工具,支援 Windows、macOS、Linux 和 FreeBSD。從 GitHub Releases 下載編譯好的執行檔就能用,不需要 Node.js 或 Docker。截至 2026 年 10 月 12 日,最新版本是 v0.32.0,發布日期是 6 月 25 日。

immich-go 的「圖形介面版」又是另一個專案:shitan198u/immich-go-gui,作者也不同。它自稱是 immich-go 的跨平台桌面前端,Windows 版有 Setup.exe 安裝檔和免安裝的 .zip。它的 README 自己提醒:執行檔沒有數位簽章,所以 Microsoft Defender 或 VirusTotal 可能把它誤判為惡意程式。要不要信任這個檔案,由你自己判斷。Immich 官方不為這兩個工具負責,出問題時要去它們各自的 GitHub 回報。

把伺服器架在 Windows 上:Immich 官方怎麼說

Immich 的系統需求頁對 Linux 以外的主機講得很直接:

Non-Linux OSes tend to provide a poor Docker experience and are strongly discouraged.

意思是:非 Linux 作業系統上的 Docker 體驗通常不好,官方強烈不建議。同一頁也寫到,官方在非 Linux 系統上能提供的安裝和除錯協助會「severely reduced」,也就是大幅減少。在 Windows 上遇到問題時,你多半要自己查。

官方沒有說「不能跑」。Windows 的路線是 Docker Desktop 搭配 WSL 2(Windows Subsystem for Linux,Windows 內建的 Linux 子系統,第 2 版)。Immich 要求使用 Docker 的 Compose 外掛,也就是 docker compose 這個指令。舊的 docker-compose 已經淘汰,官方不支援。

Docker Desktop 的授權條件和 Docker Engine 不同。在公司裡使用之前,先讀Docker Engine 與 Docker Desktop 哪個免費、授權怎麼算。

為什麼 Immich 的資料庫不能放在 Windows 磁碟

這是 Windows 上最常見的失敗原因。Immich 系統需求頁的「Special requirements for Windows users」一段寫著:

It will not work on any filesystem formatted in NTFS or ex/FAT/32. It will not work in WSL (Windows Subsystem for Linux) when using a mounted host directory (commonly under /mnt).

「It」指的是 Postgres 資料庫的資料夾,也就是 .env 裡的 DB_DATA_LOCATION。原因寫在前一句:這個資料夾必須放在「supports user/group ownership and permissions」的檔案系統上,也就是支援 Linux 使用者、群組擁有權與權限的檔案系統。NTFS 和 exFAT/FAT32 不符合這個條件。Immich FAQ 裡講資料庫擁有權錯誤的那一條,也寫明 NTFS 和 exFAT/FAT32 不受支援。

預設的 .env 寫的是 DB_DATA_LOCATION=./postgres。這是 bind mount(綁定掛載):把主機上的一個資料夾直接接進容器。如果你在 PowerShell 裡、從 C:\Users\你的名字\immich-app 啟動 compose,./postgres 就落在 NTFS 上。如果你在 WSL 裡、從 /mnt/c/... 啟動,它就是官方點名的 /mnt 掛載。兩種都不行。

Immich 自己給 Windows 使用者的解法是改用具名 volume(named volume):

1. 在 .env 裡寫 DB_DATA_LOCATION=pgdata。
2. 在 docker-compose.yml 最下面的 volumes: 區塊加一行 pgdata:。

這為什麼有效?compose 檔用 ${DB_DATA_LOCATION}:/var/lib/postgresql/data 掛載資料庫。值是路徑時,它是 bind mount。值只是一個名字時,例如 pgdata,Docker 會把它當成具名 volume,由 Docker 自己建立和管理,不對應到任何 Windows 資料夾。所以資料庫不再受你把專案資料夾放在哪裡影響。

另外兩點也來自同一頁:資料庫最好放在本機 SSD,絕對不要放在任何網路共享上;Postgres 的資料檔通常在 1 到 3 GB 之間。

開始之前:Windows 這邊要準備什麼

Docker Desktop 的 WSL 2 後端,官方列出的需求是:

• WSL 2.1.5 或更新版本,Docker 建議用最新版。
• Windows 10 64 位元 Enterprise、Pro 或 Education 22H2(組建 19045),或 Windows 11 64 位元 Enterprise、Pro 或 Education 23H2(組建 22631)以上。
• 支援 SLAT(Second Level Address Translation,第二層位址轉譯)的 64 位元處理器。
• 8 GB 系統記憶體。
• 在 BIOS/UEFI 裡開啟硬體虛擬化。

這份清單只列了 Enterprise、Pro、Education。同一頁另有一句「Windows Home or Education editions only allow you to run Linux containers」,而 Immich 的容器全是 Linux 容器。用 Windows 家用版(Home)的人,安裝前請自己對照 Docker 安裝頁的最新內容。

安裝 WSL

用「以系統管理員身分執行」的 PowerShell:

wsl --install

裝完後重新開機。Microsoft 的文件說,這個指令預設安裝 Ubuntu,新安裝的發行版預設就是 WSL 2。重開機後確認版本:

wsl.exe --list --verbose

Ubuntu 那一行標示的版本應該是 2。

設定 Docker Desktop

安裝 Docker Desktop,從開始功能表啟動,然後做兩個檢查:

1. Settings > General:如果看到「Use WSL 2 based engine」,確認它是勾選的。Docker 的文件說,在支援 WSL 2 的系統上這個選項預設開啟,而且可能根本不會顯示。
2. Settings > Resources > WSL Integration:Docker 預設只對預設的 WSL 發行版(Ubuntu)開啟整合。確認 Ubuntu 是開啟狀態,再按 Apply。

打開 Ubuntu 終端機,確認 Docker 指令能用:

docker version
docker compose version

docker version 應該同時印出 Client 和 Server 兩段。如果 Server 那段報錯,先確認 Docker Desktop 正在執行,再確認上面第 2 步的 WSL Integration 已經對 Ubuntu 開啟。

記憶體:WSL 2 預設只拿到一半

Immich 的需求是:記憶體最少 6 GB,建議 8 GB;CPU 最少 2 核心,建議 4 核心。只有 4 GB 記憶體的系統,可以在關閉機器學習功能的情況下執行 Immich。

在 WSL 2 模式下,Docker Desktop 的記憶體上限不在 Docker 自己的設定裡調整。Docker 的文件說,記憶體、CPU 和 swap 的限制要設定在 WSL 2 的虛擬機上。而 Microsoft 的文件寫明,WSL 2 虛擬機的記憶體預設是「50% of total memory on Windows」,也就是 Windows 總記憶體的一半。

算一下就知道問題在哪。一台 8 GB 的電腦,WSL 2 預設只拿到大約 4 GB,低於 Immich 的 6 GB 最低需求。一台 16 GB 的電腦,預設拿到大約 8 GB,剛好是 Immich 的建議值。

要調整,就編輯 %UserProfile%\.wslconfig。這個檔案預設不存在,需要自己建立:

[wsl2]
memory=8GB

存檔後在 PowerShell 執行:

wsl --shutdown

然後重新啟動 Docker Desktop,新的上限才會生效。Microsoft 也提供開始功能表裡的「WSL Settings」程式,可以用圖形介面改同樣的設定。

別忘了 Windows 自己也要用記憶體。8 GB 的電腦就算把 6 GB 分給 WSL 2,Windows 也只剩 2 GB,開個瀏覽器就很吃緊。照片數量和記憶體、硬碟的關係,可以參考Immich 的記憶體與儲存空間需求。

一步一步在 WSL 裡架起 Immich

專案資料夾放在哪裡,直接影響速度。Docker 的 WSL 2 最佳實務頁寫著「Performance is much higher when files are bind-mounted from the Linux filesystem」,並且明確要你避免從 /mnt/c 掛載。Microsoft 的 WSL 文件也說,在 Linux 命令列工作時,檔案存在 WSL 的檔案系統裡速度最快。兩家都沒有給出具體數字。

所以下面的做法是:整個 Immich 專案資料夾放在 Ubuntu 的家目錄裡,所有指令都在 Ubuntu 終端機裡執行。這樣也可以直接用 Immich 官方文件上的 wget 指令,不必改寫成 PowerShell 版本。

下載官方的 compose 檔與設定檔

mkdir ~/immich-app
cd ~/immich-app
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

如果系統說找不到 wget,先執行 sudo apt install -y wget。截至 2026 年 10 月 12 日,latest 指向的是 v3.3.1,發布日期是 10 月 8 日。

修改 .env

先產生一組資料庫密碼。官方要求密碼只用 A-Za-z0-9 這些字元,不要有特殊符號或空白。openssl rand -hex 輸出的只有數字和小寫字母,符合規定:

openssl rand -hex 24
nano .env

把下面幾行改成這樣,其他行不動:

UPLOAD_LOCATION=./library
DB_DATA_LOCATION=pgdata
IMMICH_VERSION=v3
DB_PASSWORD=PasteTheOpensslOutputHere

UPLOAD_LOCATION=./library 是照片庫的位置。保持預設,它就在 Ubuntu 的家目錄裡。DB_DATA_LOCATION=pgdata 是前面講的具名 volume。IMMICH_VERSION=v3 會跟著 v3 系列更新。想自己決定何時升級,可以釘在 v3.3.1 這樣的完整版本號。

在 compose 檔加上 pgdata

官方的 docker-compose.yml 結尾是一個最上層的 volumes: 區塊,裡面只有 model-cache:。用 nano docker-compose.yml 打開,在最後加一行,縮排和 model-cache: 對齊:

volumes:
  model-cache:
  pgdata:

存檔後檢查:

docker compose config --volumes

這個指令會解析整份 compose 檔,並列出所有具名 volume。清單裡應該有 model-cache 和 pgdata。如果它報 YAML 錯誤,先檢查縮排有沒有對齊。

啟動並確認

docker compose up -d
docker compose ps
docker volume ls

第一次啟動要下載好幾個映像檔,需要一點時間。等幾分鐘後再跑一次 docker compose ps,確認沒有服務一直處在 Restarting 狀態。docker volume ls 裡應該看得到一個名稱以 pgdata 結尾的 volume。伺服器起不來時,看它的紀錄:

docker compose logs -f immich-server

一切正常後,在 Windows 的瀏覽器打開 http://localhost:2283,註冊第一個帳號,它就是管理員。

手機要連的是這台電腦在家用網路裡的 IP。在 PowerShell 執行 ipconfig,找到你的 Wi-Fi 或有線網卡的 IPv4 位址,在 App 裡填 http://那個IP:2283。如果電腦本機能開,手機卻連不上,先檢查 Windows 防火牆有沒有擋下 2283 埠的連入連線。

照片庫可以放在 Windows 的 D 槽嗎?

很多人的大容量硬碟是 Windows 的 D 槽,所以會想把 UPLOAD_LOCATION 指到 /mnt/d/...。Immich 文件對這件事沒有明確說可以或不可以。它對資料庫有明確的 NTFS 禁令,對照片庫只有一句建議:放在「Unix-compatible filesystem (EXT4, ZFS, APFS, etc.) with support for user/group ownership and permissions」上,也就是支援擁有權與權限的類 Unix 檔案系統。NTFS 不在這份清單裡。

速度方面,前面引用的 Docker 和 Microsoft 文件都指向同一個方向:從 /mnt 掛載的 Windows 磁碟,比 WSL 自己的檔案系統慢。慢多少,兩家都沒有給數字。

建議是照片庫留在 WSL 的檔案系統裡。要從 Windows 檔案總管看這些照片,可以走 \\wsl$ 這個網路路徑,例如 \\wsl$\Ubuntu\home\你的帳號\immich-app\library。如果你還是要放 D 槽,這是官方文件沒有涵蓋的組合。請先用少量照片測試上傳、縮圖和刪除都正常,再搬整個相簿進去。

空間也要預留。Immich 說縮圖和轉檔後的影片,平均會讓照片庫變大 10% 到 20%。各個資料夾實際存了什麼,Immich 用 Docker 時照片實際存在哪裡有逐一說明。

用自己的電腦當伺服器,家裡會遇到的問題

電腦睡眠或關機時,手機備份傳不上去

Immich 的手機備份分兩種。前景備份在你打開或切回 App 時,把選定相簿裡的新照片和影片傳上去。背景備份會定期執行,但文件沒有給出固定的時間表。在 iOS 上,背景工作何時執行由系統決定,App 無法控制。預設只在 Wi-Fi 下上傳。

不管哪一種,上傳都需要伺服器在線。電腦一睡眠,伺服器就連不到,手機上的新照片只能留在手機裡,等伺服器在線時再傳。Windows 11 的睡眠設定在「設定 > 系統 > 電源與電池」的螢幕與睡眠逾時選項裡(英文介面是 Settings > System > Power & battery > Screen, sleep, & hibernate timeouts)。如果要把這台電腦當伺服器,就把插電時的睡眠時間設得夠長;你的電腦有「永不」選項的話,就選它。

Windows Update 重開機後,Immich 不一定會回來

更新要裝完,電腦就得重新開機。Microsoft 的說法是,自動重開機會避開「使用時間」(active hours)。預設是早上 8 點到下午 5 點,使用者可以自己改,較新的 Windows 版本最長可以設 18 小時。路徑是「設定 > Windows Update > 進階選項 > 使用時間」。這只保護你設定的那段時間,不會讓電腦永遠不重開。

重開機之後才是真正的問題。Immich 的 compose 檔裡每個服務都設了 restart: always,但這只有在 Docker 本身在跑時才有用。Docker Desktop 的「Start Docker Desktop when you sign in to your computer」設定,預設是關閉的。也就是說,重開機後 Docker Desktop 不會自己啟動,Immich 就一直停著,直到有人手動打開 Docker Desktop。

把這個設定打開。不過它的字面意思是「登入時」啟動。電腦重開後停在登入畫面時 Immich 能不能回來,請自己測一次:重新開機,先不要登入,用手機打開 App,看看能不能連上。

從外面連回家裡的 Immich

Immich 的遠端存取指南列了三種做法:用 VPN 連回家裡的網路、用 Tailscale,或是架反向代理。同一頁有一句警告:沒有其他設定的情況下,絕對不要把 2283 埠直接轉發到網際網路上。

備份:具名 volume 不是備份

把資料庫放進具名 volume,只解決了「能不能跑」,沒有解決「壞了怎麼辦」。Immich 建議 3-2-1 備份策略,並特別強調資料庫備份非常重要,因為 Immich 不會掃描照片庫資料夾來重建資料。

好消息是,Immich 會自動把資料庫匯出到 UPLOAD_LOCATION/backups,預設每天凌晨 2 點做一次,保留最近 14 份。照上面的設定,這個資料夾在 ~/immich-app/library/backups。它是一般資料夾,不在 volume 裡,所以從 Windows 檔案總管就能把它複製到外接硬碟。

注意,資料庫備份只有中繼資料,不包含照片和影片,必須和 UPLOAD_LOCATION 裡的檔案一起使用。官方列出的關鍵資料夾是 library、upload 和 profile,其中只有原始內容是真正不能遺失的。

留在電腦上,還是把伺服器搬出去?

決定的關鍵只有一個:你要不要在電腦關著的時候也能用 Immich。

如果這台電腦本來就整天開著,你也只在家裡看照片,那 Immich 留在電腦上就可以。照上面的方式設好具名 volume、WSL 記憶體、睡眠時間和 Docker Desktop 登入時啟動,它就能正常運作。

如果你希望人在外面時手機也能隨時備份,或者不想讓伺服器跟著 Windows Update 和睡眠設定停停走走,就把伺服器搬到 NAS 或 VPS 這類一直開著的 Linux 機器上。Windows 電腦改當上傳端:用官方 CLI 或 immich-go,把電腦裡的照片傳上去。伺服器改用 Linux 原生的檔案系統之後,前面講的 NTFS 和 /mnt 問題就不會出現。完整的 Linux 伺服器架法,可以照著在 VPS 上自架 Immich,取代 Google 相簿一步步做。還在比較要用哪一套照片管理軟體的話,先看PhotoPrism 與 Immich 的比較。

FAQ

Immich 有官方的 Windows 版程式可以下載嗎?

Immich 官方文件提供的是網頁介面、手機 App 和命令列工具 @immich/cli,文件裡找不到官方的 Windows 桌面程式。在 Windows 上,用瀏覽器打開 http://伺服器IP:2283 就能使用。immich-go 和它的圖形介面版是兩個不同作者的社群專案,不是 Immich 官方出品。

為什麼 Immich 的資料庫不能放在 NTFS 或 /mnt/c?

Immich 的系統需求頁寫明,Postgres 資料夾(DB_DATA_LOCATION)必須放在支援使用者、群組擁有權與權限的檔案系統上。所以它在 NTFS、exFAT/FAT32,以及 WSL 裡的 /mnt 掛載上都無法運作。官方的解法是在 .env 寫 DB_DATA_LOCATION=pgdata,並在 docker-compose.yml 最後的 volumes: 下加 pgdata:,讓資料庫改用 Docker 管理的具名 volume。

8 GB 記憶體的 Windows 電腦能跑 Immich 嗎?

很吃緊。Immich 最少要 6 GB,建議 8 GB。WSL 2 預設只拿 Windows 總記憶體的一半,所以 8 GB 的電腦只分到大約 4 GB。你可以在 %UserProfile%\.wslconfig 的 [wsl2] 下調高 memory=,再執行 wsl --shutdown,但 Windows 自己剩下的記憶體就很少。Immich 也說,4 GB 的系統可以在關閉機器學習功能時執行。

電腦睡眠或關機時,手機拍的照片會怎樣?

伺服器連不到,手機就無法上傳,新照片會留在手機上。Immich 的前景備份會在你下次打開或切回 App 時,把選定相簿裡的新照片傳上去。背景備份的時間由系統決定,在 iOS 上 App 無法控制。如果你需要隨時都能備份,伺服器就要放在一直開著的機器上,例如 NAS 或 VPS。