Jellyfin Docker NVIDIA 硬體轉碼設定教學

您正在建置的內容

在 NVIDIA GPU 上進行 Jellyfin 硬體轉碼的過程分為四個固定順序的步驟，且只有最後一步是在 Jellyfin 內部執行。若主機驅動程式未載入，容器將無法識別 GPU；若容器無法識別 GPU，Jellyfin 便無法使用它。請依照此順序操作，如此一來，若發生錯誤，便能明確找出問題所在。

1. 在主機安裝 NVIDIA 驅動程式，並使用 nvidia-smi 進行確認。
2. 安裝 NVIDIA Container Toolkit，以便 Docker 能將 GPU 指派給容器。
3. 在 docker-compose.yml 中為 Jellyfin 服務保留 GPU，並確認容器能識別該裝置。
4. 在 Jellyfin 的播放設定中啟用 NVENC 與 NVDEC，並確認實際播放時有使用這些功能。

NVENC (NVIDIA encoder) 與 NVDEC (NVIDIA decoder) 是顯示卡上的固定功能區塊。它們與執行 CUDA (compute unified device architecture) 運算的著色器核心 (shader cores) 在矽晶片上是分開的。這種分離正是此方案的價值所在：原本在軟體轉碼中會消耗數個 CPU 核心的串流，現在只需佔用極少量的 CPU 資源，並由 GPU 上的專用硬體區塊處理。

直接播放優於所有轉碼，請優先檢查此項

在進行任何設定前，請先確認您是否為了可以輕易排除的原因而進行轉碼。當客戶端無法播放檔案時，Jellyfin 就會進行轉碼。原因通常不外乎以下幾種：視訊編碼、音訊編碼、容器格式、基於影像的字幕，或是客戶端要求的位元率限制。

開啟 Dashboard，進入 Playback，並在播放時觀察作用中的連線階段（active session）。標記為 Direct playing 的連線會直接傳送原始檔案，幾乎不消耗 CPU。標記為 Transcoding 的連線則會顯示 Jellyfin 選擇轉碼的原因。排除該原因後，GPU 便無需運作。

兩項變更可消除大多數的轉碼需求。將客戶端應用程式的畫質設定為 Auto 或最高，因為客戶端若要求 4 Mbps，無論檔案使用何種編碼，系統都會強制將 20 Mbps 的檔案重新編碼。此外，請使用原生客戶端應用程式而非瀏覽器分頁，因為瀏覽器是您所有裝置中最受限的播放器，而同一台電視上的原生應用程式通常能直接播放相同的檔案。

基於影像的字幕是無法透過客戶端設定解決的例外情況。來自 Blu-ray 備份的 PGS 字幕與 DVD 備份的 VOBSUB 字幕皆為圖片，因此必須繪製在視訊上，這意味著必須對視訊串流進行完整重新編碼。SRT 文字字幕則會以獨立軌道傳送至客戶端，不會造成額外負擔。若能將字幕軌道轉換為文字格式，其效益遠高於升級 GPU。伺服器端的其餘設定請參閱 在 VPS 上執行 Jellyfin 媒體伺服器的指南。

大多數 VPS 方案皆不具備 GPU

標準 VPS 方案不包含 GPU。在進行任何規劃前，請先在伺服器上執行此指令。

lspci -nn | grep -Ei "3d|display|vga"

在典型的 KVM VPS 上，此指令僅會顯示來自 Hypervisor 的虛擬顯示介面，或無法提供任何實質資訊。該裝置無法進行影片編碼。唯有當供應商將實體顯示卡透傳（passthrough）至您的執行個體，或提供切分後的 GPU 資源時，才會出現真正的 GPU，而這類方案的價格也相對較高。哪些工作負載才值得租用 GPU VPS 一文說明了適用與不適用此類方案的對象。

若伺服器沒有 GPU，請以「直接播放」（direct play）為目標，並將軟體轉碼視為極少數的例外情況。單一 1080p H.264 軟體轉碼雖然負載沉重，但使用數個 CPU 核心尚可應付。至於 4K HDR 軟體轉碼並包含色調映射（tone mapping），小型 VPS 無法即時完成，這會導致 CPU 使用率飆升至 100%，並造成串流播放卡頓。

在宿主機上安裝 NVIDIA 驅動程式

Jellyfin 10.11 文件指出 Linux 系統上的 NVIDIA 驅動程式最低版本需求為 520.56.06。Ubuntu 內建輔助工具，可協助您選擇合適的套件。

sudo ubuntu-drivers list --gpgpu
sudo ubuntu-drivers install --gpgpu
sudo reboot

--gpgpu 會選取驅動程式的 headless server 版本，這正是媒體伺服器所需的，因為該機器並未安裝桌面環境。列出指令會顯示您可用的分支，您可以指定其中一個名稱進行鎖定，例如 sudo ubuntu-drivers install --gpgpu nvidia:570-server。請務必使用清單中實際顯示的分支，而非此處範例的名稱。

server 版本不一定會自動安裝 nvidia-smi。請針對您選擇的分支安裝對應的 utils 套件，例如 sudo apt install nvidia-utils-570-server。安裝完成後，請檢查驅動程式狀態。

nvidia-smi

若運作正常，系統會顯示一個表格，標題包含驅動程式版本與 CUDA 版本，並列出您的顯示卡名稱，且處理程序列表應為空。此處常見兩種錯誤。nvidia-smi: command not found 代表缺少 utils 套件，而非驅動程式問題。NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver 代表核心模組未載入；在全新安裝的情況下，這通常是因為尚未重新開機，或是 Secure Boot 拒絕載入未簽章的模組。請使用 lsmod | grep nvidia 確認模組是否存在。

安裝 NVIDIA Container Toolkit

驅動程式讓主機得以使用 GPU。但 Docker 預設不會將其傳遞至容器，因為容器內缺乏裝置節點與驅動程式函式庫。NVIDIA Container Toolkit 的作用是在容器啟動時注入這些元件。以下是 NVIDIA 針對 Debian 與 Ubuntu 提供的官方安裝指令。

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

僅安裝套件並不足夠，必須告知 Docker 該執行階段（runtime）的存在。

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

nvidia-ctk runtime configure 會在 /etc/docker/daemon.json 中寫入 nvidia 執行階段項目。重啟服務是許多人會遺漏的步驟，而忽略此步驟是整個設定過程中導致錯誤的主因。在操作 Jellyfin 之前，請先測試管線是否暢通。

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

此指令應輸出與主機端相同的表格。若執行失敗並顯示無法選擇具備 gpu 功能之裝置驅動程式的錯誤，代表 Docker daemon 未識別 nvidia 執行階段，請再次執行設定指令並重啟 daemon。

將 GPU 資源分配給 Docker Compose 中的 Jellyfin 容器

這是符合 Jellyfin 官方範例的現代化 Compose 寫法。

services:
  jellyfin:
    image: jellyfin/jellyfin
    container_name: jellyfin
    user: 1000:1000
    network_mode: host
    restart: unless-stopped
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=all
    volumes:
      - /srv/jellyfin/config:/config
      - /srv/jellyfin/cache:/cache
      - /srv/media:/media:ro
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

啟動服務並直接向容器查詢。

docker compose up -d
docker compose exec jellyfin nvidia-smi

若指令成功從容器內部輸出驅動程式列表，代表 GPU 已正確透傳（passthrough），後續若有問題皆屬於 Jellyfin 軟體設定範疇。

該檔案中的四行設定需要特別說明。capabilities: [gpu] 是 Compose 本身所必需，若省略此行，Compose 會拒絕啟動該服務，而非在沒有 GPU 的情況下執行。NVIDIA_DRIVER_CAPABILITIES=all 至關重要，因為只有在請求視訊功能時，工具組才會將視訊函式庫掛載至容器內，且 Jellyfin 文件明確指出官方映像檔必須設定此變數。若未設定，CUDA 可正常運作但 NVDEC 會失效，轉碼日誌將顯示 Cannot load libnvcuvid.so.1。network_mode: host 是 Jellyfin 官方範例採用的設定，因為 UDP 埠 7359 的用戶端自動探索功能無法在 bridge 網路模式下運作。

user: 1000:1000 是最後一項，它與 GPU 無關。此設定決定了 Jellyfin 能讀取媒體掛載點中的哪些檔案；若設定不符，媒體庫會顯示為空，而非出現權限錯誤。PUID 與 PGID 如何將容器使用者對應至磁碟檔案 一文解釋了編號邏輯，若您已在 Docker Compose 中的 Sonarr 與 Radarr 堆疊 執行過相關設定，請使用相同的編號。

為何大多數教學仍使用 runtime: nvidia

舊有的寫法幾乎出現在您能找到的每一份指南中，這並非錯誤，而是歷史遺留問題。最初的 nvidia-docker2 套件註冊了一個名為 nvidia 的 OCI 執行時期，因此將 GPU 導入容器的唯一方法就是使用 --runtime=nvidia 加上 NVIDIA_VISIBLE_DEVICES。Docker 19.03 新增了 --gpus 旗標與正確的裝置請求 API。Docker Compose 的跟進速度較慢，當它支援時，裝置請求功能被歸類在 deploy.resources.reservations.devices 下；這是一個大多數人已習慣忽略的鍵值，因為 deploy 過去通常是指 Docker Swarm。

結果是這兩種寫法在今日皆可運作，Jellyfin 發布的範例也同時包含了兩者。保留 runtime: nvidia 並不會造成額外負擔，且能確保檔案在較舊的 Compose 版本上運作。若您僅保留 runtime: nvidia 並移除 deploy 區塊，則必須保留 NVIDIA_VISIBLE_DEVICES=all，因為該舊有路徑會讀取環境變數來決定要注入哪些裝置，且沒有對應的裝置請求可供讀取。

在 Jellyfin 中啟用 NVIDIA 硬體轉碼

目前尚未設定 Jellyfin 使用該顯示卡。請前往 Dashboard，接著點選 Playback，再進入 Transcoding。將 Hardware acceleration 設定為 Nvidia NVENC。請勾選 Enable hardware encoding，否則 Jellyfin 會在 GPU 上解碼後再交由 CPU 編碼，這會導致 GPU 顯示運作中但 CPU 負載依然偏高的混亂狀態。

Enable enhanced NVDEC decoder 可在目前的 NVDEC 路徑與舊版 CUVID 路徑間切換。請保持開啟。若要使用 NVDEC 處理 Dolby Vision，必須啟用此選項。

在 Enable hardware decoding for 下方，僅勾選您的顯示卡實際支援解碼的編解碼器。這是最容易設定錯誤的地方。若在不支援 AV1 的顯示卡上勾選 AV1，系統不會顯示錯誤訊息。Jellyfin 會嘗試請求硬體解碼，若失敗則會退回軟體解碼，導致 CPU 負載過高而 GPU 幾乎閒置，看起來就像直通（passthrough）功能完全失效一樣。

此頁面還有一個整體限制：硬體加速僅適用於隨附的 jellyfin-ffmpeg 建置版本。若您將 FFmpeg 路徑指向系統內建的 FFmpeg，將會導致加速功能部分失效或完全無法運作。

您的 GPU 世代支援哪些編解碼器

這是 Jellyfin 針對 NVENC 與 NVDEC 所記錄的界限。解碼與編碼是獨立的功能，顯示卡可能具備其中之一，卻不支援另一項。

• H.264 8-bit：所有具備 NVENC 與 NVDEC 的 NVIDIA GPU 皆可進行編解碼。
• HEVC 8-bit：從 Maxwell 第二代 (GM206) 及更新版本開始支援編解碼。
• HEVC 10-bit：從 Maxwell 第二代及更新版本開始支援解碼，但僅 Pascal 及更新版本支援編碼。
• AV1：從 Ampere 及更新版本開始支援解碼，從 Ada Lovelace 及更新版本開始支援編碼。

HEVC 10-bit 的差異在實務上最常造成問題。Maxwell 世代的顯示卡雖能在 GPU 上解碼 4K HDR 檔案，卻無法編碼 10-bit 輸出，因此 Jellyfin 會改為編碼成 8-bit H.264。這仍可正常播放，且對大多數用戶端而言也是正確的選擇。無論您的顯示卡為何，在 2026 年通常都不建議使用 AV1 編碼，因為用戶端對 AV1 的解碼支援度依然有限，且轉碼的目的本就是為了服務那些效能不足的用戶端。

為何色調映射會悄悄耗盡 GPU 資源

將 HDR (high dynamic range) 轉換為 SDR (standard dynamic range) 的色調映射設定，是導致 GPU 資源耗盡的主因，其原因在於架構設計。解碼工作由 NVDEC 執行，編碼工作由 NVENC 執行，但色調映射兩者皆不使用：它是以 CUDA 濾鏡形式在著色器核心 (shader cores) 上執行，這與執行運算任務的 GPU 通用處理單元相同。因此，一個需要色調映射的 4K HDR 串流，不僅會佔用解碼器與編碼器，還會額外加載著色器。

Jellyfin 將 CUDA 色調映射標示為適用於所有支援 HEVC 10-bit 解碼的 NVIDIA GPU。這意味著即使在無法負荷 4K 處理的顯示卡上，該選項仍會出現並可勾選。其症狀是串流啟動後不斷緩衝，始終無法順暢播放，而 nvidia-smi 顯示編碼器負載極低。

這就是為什麼需要單獨監控著色器負載的原因。

nvidia-smi dmon -s u

該指令會每秒輸出一行數據，並分別顯示 sm、enc 與 dec 的數值。若 enc 與 dec 數值偏低但 sm 數值偏高，代表固定功能區塊處於閒置狀態，而著色器正是效能瓶頸，這表示色調映射、縮放或字幕燒錄 (subtitle burn-in) 佔用了過多資源。CUDA 路徑亦支援以 zero copy 處理 Dolby Vision profile 5，這點至關重要；若無 zero copy，影格會在濾鏡處理步驟間傳輸至系統記憶體再傳回，這種往返會對每個影格造成頻寬損耗。

消費級 NVENC 工作階段上限的實際限制

[
  {
    "label": "GeForce RTX 5090",
    "nvenc_engines": 3,
    "max_encode_sessions": 12
  },
  {
    "label": "GeForce RTX 4090",
    "nvenc_engines": 2,
    "max_encode_sessions": 12
  },
  {
    "label": "GeForce RTX 4060",
    "nvenc_engines": 1,
    "max_encode_sessions": 12
  }
]

上述數據為 NVIDIA 截至 2026 年 8 月發布的矩陣數值，非本站實測結果。無論型號為何，GeForce 顯示卡的並發編碼工作階段上限皆為 12。此限制存在於驅動程式而非晶片層級，且 NVIDIA 多年來已多次調升上限，請務必參閱最新矩陣，切勿參考過時的論壇討論。硬體編碼器數量（Engine count）才是隨顯示卡型號變動的規格：GeForce RTX 5090 搭載 3 個 NVENC 編碼器，而 GeForce RTX 4060 則搭載 1 個。編碼器數量增加代表並行編碼吞吐量提升，而非提高工作階段上限。

此上限僅計算編碼工作階段，因此僅針對轉碼串流。直接播放（Direct play）與封裝轉換（Remuxing）不會開啟編碼工作階段。資料中心級顯示卡（如 L4）在同一矩陣中列為無限制，而 GPU VPS 方案通常提供此類卡片，因此該上限主要影響家用伺服器。

當達到上限時，轉碼會失敗並在 FFmpeg 日誌中顯示 OpenEncodeSessionEx failed: out of memory (10)。該錯誤訊息雖提及記憶體，但工作階段限制拒絕請求時也會回報相同代碼，因此在排查 VRAM 洩漏前，請先確認並發串流數量。實務上，大多數使用者在達到 12 個工作階段前，就會先遇到色調映射（Tone-mapping）效能瓶頸或上傳頻寬限制。

驗證 GPU 是否正在進行轉碼，切勿僅憑設定判斷

儲存的設定並非實際運作的證據。請播放一個您確定會觸發轉碼的檔案，接著執行以下三項檢查。

1. 開啟 Dashboard，進入 Playback。作用中的工作階段應顯示 Transcoding，並註明原因。若顯示 Direct playing，代表並未進行轉碼，您測試的檔案有誤。
2. 開啟 Dashboard，進入 Logs，並開啟最新的 FFmpeg.Transcode 日誌。硬體轉碼會在指令列中顯示 -hwaccel cuda 與 -hwaccel_output_format cuda，且編碼器為 h264_nvenc 或 hevc_nvenc。若看到 libx264，代表無論設定頁面如何顯示，您目前仍在使用軟體轉碼。
3. 在播放持續進行時，於主機端執行 nvidia-smi。此時應出現來自 /usr/lib/jellyfin-ffmpeg/ffmpeg 的處理程序，且 GPU 記憶體已配置；nvidia-smi dmon -s u 應顯示非零的 enc 與 dec 數值。

請在主機端執行第三項檢查，而非在容器內部。在容器內執行 nvidia-smi 通常會顯示空白的處理程序列表，因為容器無法看見自身命名空間以外的處理程序 ID，儘管使用率數值仍會正確顯示。容器內部的處理程序列表為空並非故障。

當系統在未通知的情況下自動降級為軟體解碼

Jellyfin 傾向於維持播放。當硬體路徑不可用時，它會降級為軟體解碼而非直接中斷串流，因此判斷依據應為 CPU 負載與 FFmpeg 日誌，而非錯誤橫幅。

Cannot load libnvcuvid.so.1 出現在轉碼日誌中，代表解碼器函式庫未掛載至容器內。請設定 NVIDIA_DRIVER_CAPABILITIES=all 並重建容器，因為環境變更需要 docker compose up -d 才能重新建置，單純重啟容器會保留舊設定。

來自 h264_nvenc 的 No capable devices found 代表 FFmpeg 已觸及編碼器函式庫，但找不到可用的顯示卡。請再次檢查 docker compose exec jellyfin nvidia-smi，這通常代表裝置保留權限已移除，或是容器由過時的檔案重建。

若 CPU 使用率偏高但 GPU 靜止，代表解碼端正發生靜默失敗。請取消勾選您該世代硬體無法解碼的編解碼器，重新播放相同檔案，並再次讀取 FFmpeg 日誌以確認是否出現 -hwaccel cuda。

若轉碼在處理 4K HDR 時啟動後停滯，但 1080p 播放正常，這屬於色調映射（tone-mapping）的效能上限，而非安裝損壞。請在 nvidia-smi dmon -s u 的 sm 欄位確認此狀況，接著調降用戶端請求的解析度，或是僅在支援直接播放（direct play）的用戶端上播放 4K HDR 檔案。

FAQ

為什麼啟用 NVENC 後 Jellyfin 仍在使用 CPU？

請檢查儀表板（Dashboard）下方的最新 FFmpeg.Transcode 日誌。若顯示 libx264，代表完全未使用硬體路徑，通常是因為容器無法存取 GPU，請執行 docker compose exec jellyfin nvidia-smi 進行確認。若顯示 h264_nvenc 但 CPU 負載依然偏高，代表解碼部分仍以軟體執行；這通常發生在勾選了顯示卡不支援的編解碼器，或是未開啟「啟用硬體編碼」（Enable hardware encoding），導致僅有一半的處理流程移至 GPU。

我還需要在 Docker Compose 中加入 runtime: nvidia 這一行嗎？

若您已設定 deploy.resources.reservations.devices 區塊且使用新版 Docker Compose，則不需要。該區塊是現代的裝置請求格式，功能相同。runtime: nvidia 是來自 nvidia-docker2 時代的舊路徑，目前仍可運作，Jellyfin 官方範例也保留了兩者。同時保留並無害處。若僅保留 runtime: nvidia，則必須同時保留 NVIDIA_VISIBLE_DEVICES=all，因為該路徑沒有讀取裝置請求，而是從環境變數中取得裝置列表。

一張 NVIDIA GPU 同時能轉碼多少串流？

截至 2026 年 8 月，NVIDIA 公布的規格表將 GeForce 系列顯示卡的並發編碼工作階段限制為 12 個，資料中心等級顯示卡則無此限制。但通常限制您的並非此上限。HDR 轉 SDR 的色調映射（tone mapping）是在著色器核心（shader cores）而非 NVENC 上執行，因此少量的 4K HDR 串流就會在工作階段計數達到上限前，先耗盡著色器資源。請使用 nvidia-smi dmon -s u 監控實際狀況，並觀察 sm 欄位而非工作階段計數。

我可以在沒有 GPU 的 VPS 上使用硬體轉碼嗎？

不行。編碼需要實體的 NVENC 區塊，而標準 VPS 上的 lspci -nn | grep -Ei "3d|display|vga" 僅會顯示虛擬化管理程式提供的虛擬顯示轉接器。在沒有 GPU 的方案中，實際的解決方案是移除轉碼需求：將用戶端的畫質設定調為 Auto，使用原生用戶端應用程式而非瀏覽器，並將影像格式的字幕軌轉換為文字格式，以避免強制觸發影片重新編碼。

為什麼 1080p 轉碼正常，但 4K HDR 會卡頓？

這兩種工作負載使用了顯示卡的不同區塊。1080p SDR 轉碼僅涉及解碼與編碼，兩者皆由固定功能硬體處理。4K HDR 串流則增加了色調映射，這是執行在著色器核心上的 CUDA 濾鏡，且需處理更大的縮放幀。若 nvidia-smi dmon -s u 顯示 enc 與 dec 數值偏低但 sm 數值偏高，即可確認此問題，因為該模式代表固定功能區塊處於閒置，而通用核心已達效能瓶頸。