Настройка NVIDIA транскодирования в Jellyfin Docker

Что вы создаете

Аппаратное транскодирование Jellyfin на GPU NVIDIA выполняется в четыре этапа в строгом порядке, и только последний из них происходит внутри Jellyfin. Контейнер не может обнаружить GPU, если драйвер хоста не загружен. Jellyfin не может использовать GPU, который не виден контейнеру. Выполняйте действия в указанном порядке, чтобы в случае сбоя сразу понимать, где искать причину.

1. Установите драйвер NVIDIA на хост-систему, затем подтвердите его работу с помощью nvidia-smi.
2. Установите NVIDIA Container Toolkit, чтобы Docker мог передавать GPU в контейнер.
3. Зарезервируйте GPU для сервиса Jellyfin в docker-compose.yml, затем убедитесь, что контейнер видит устройство.
4. Включите NVENC и NVDEC в настройках воспроизведения Jellyfin, затем убедитесь, что при реальном воспроизведении они используются.

NVENC (NVIDIA encoder) и NVDEC (NVIDIA decoder) — это специализированные аппаратные блоки на видеокарте. Они физически отделены от шейдерных ядер, которые выполняют вычисления CUDA (compute unified device architecture). Именно это разделение делает данную настройку эффективной: поток, который при программном кодировании потребляет несколько ядер CPU, при аппаратном требует лишь малую часть одного ядра и выделенный аппаратный блок на GPU.

Direct play эффективнее любого транскодирования, поэтому начните с проверки этого режима

Прежде чем приступать к настройке, выясните, нет ли у вас причин для транскодирования, которые можно просто устранить. Jellyfin выполняет транскодирование, если клиент не может воспроизвести файл в исходном виде. Причина всегда кроется в одном из пунктов короткого списка: видеокодек, аудиокодек, формат контейнера, субтитры на основе изображений или ограничение битрейта, запрошенное клиентом.

Откройте Dashboard, затем Playback и наблюдайте за активным сеансом во время воспроизведения. Сеанс с пометкой Direct playing передает файл без изменений и почти не потребляет ресурсы CPU. Сеанс с пометкой Transcoding показывает причину, по которой Jellyfin выбрал этот режим. Устраните эту причину, и GPU не придется работать вовсе.

Два изменения позволяют исключить большинство случаев транскодирования. Установите качество в клиентском приложении на Auto или на максимум, так как клиент, запрашивающий 4 Mbps, принудительно вызывает перекодирование файла с битрейтом 20 Mbps, независимо от используемого кодека. Затем используйте нативное клиентское приложение вместо вкладки браузера, так как браузер — это самый ограниченный плеер из всех, что у вас есть, а нативное приложение на том же телевизоре часто воспроизводит тот же самый файл в режиме Direct play.

Субтитры на основе изображений — это исключение, которое не исправляется настройками клиента. Субтитры PGS из рипов Blu-ray и VOBSUB из рипов DVD представляют собой изображения, поэтому их приходится «врисовывать» прямо в видеопоток, что означает полное перекодирование видео. Текстовые субтитры в формате SRT передаются клиенту отдельной дорожкой и не требуют ресурсов. Конвертация дорожек субтитров в текстовый формат там, где это возможно, полезнее, чем наличие мощного GPU. Остальные аспекты настройки сервера описаны в руководстве по запуску медиасервера Jellyfin на VPS.

Большинство тарифов VPS не включают GPU

Стандартные тарифы VPS не предусматривают наличие GPU. Выполните эту команду на сервере, прежде чем планировать что-либо еще.

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

На обычном KVM VPS эта команда выведет виртуальный графический адаптер гипервизора или не выдаст ничего полезного. Это устройство не способно выполнять кодирование видео. Настоящий GPU появляется только в том случае, если провайдер предоставляет проброс физической карты в ваш инстанс или выделяет его часть, при этом стоимость таких тарифов значительно выше. В разделе Какие рабочие нагрузки действительно оправдывают использование GPU VPS описано, кому это необходимо, а кому нет.

Если GPU отсутствует, ориентируйтесь на прямое воспроизведение (direct play), а программное транскодирование рассматривайте как исключительный случай. Одно программное транскодирование 1080p H.264 создает высокую нагрузку, но допустимо для нескольких ядер CPU. Программное транскодирование 4K HDR с тональной компрессией (tone mapping) — это задача, с которой небольшой VPS не справится в реальном времени, поэтому поток будет прерываться, а загрузка CPU достигнет 100 процентов.

Установка драйвера NVIDIA на хост

Jellyfin 10.11 требует версию драйвера NVIDIA не ниже 520.56.06 для Linux. В Ubuntu есть встроенная утилита, которая подбирает подходящий пакет автоматически.

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

--gpgpu выбирает серверную версию драйвера без графической оболочки (headless), что оптимально для медиасервера, так как на хосте нет рабочего стола. Команда вывода списка показывает доступные ветки драйверов; вы можете зафиксировать конкретную версию по имени, например, sudo ubuntu-drivers install --gpgpu nvidia:570-server. Используйте ветку, которая отобразилась в вашем списке, а не ту, что указана здесь в качестве примера.

Серверная версия не всегда автоматически устанавливает nvidia-smi. Установите соответствующий пакет утилит для выбранной ветки, например, sudo apt install nvidia-utils-570-server. После этого проверьте состояние драйвера.

nvidia-smi

При корректной работе выводится таблица, где в заголовке указаны версии драйвера и CUDA, ниже приведено название вашей видеокарты, а список процессов пуст. Часто встречаются две ошибки. nvidia-smi: command not found означает, что отсутствует пакет утилит, а не сам драйвер. 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 добавляет запись о runtime nvidia в файл /etc/docker/daemon.json. Перезапуск — это этап, который часто пропускают, и именно это приводит к самой распространенной ошибке во всей настройке. Проверьте работоспособность связки перед тем, как переходить к Jellyfin.

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

Эта команда должна вывести ту же таблицу, что и на хосте. Если вместо этого возникает ошибка о невозможности выбрать драйвер устройства с возможностями gpu, значит, Docker daemon не знает о runtime nvidia. В этом случае выполните команду настройки еще раз и перезапустите daemon.

Предоставление GPU контейнеру Jellyfin в Docker Compose

Это современный формат Compose, соответствующий примеру, который публикует Jellyfin.

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 проброшен корректно, и все оставшиеся проблемы связаны с настройками 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 сопоставляют пользователя контейнера с файлами на диске объясняется нумерация; это те же значения, которые вы уже задали, если запускаете стек Sonarr и Radarr в Docker Compose рядом с этим сервисом.

Почему в большинстве руководств до сих пор пишут runtime: nvidia

Старый формат встречается почти в каждом руководстве, и это не ошибка. Это история. Исходный пакет nvidia-docker2 регистрировал OCI-рантайм с именем nvidia, поэтому единственным способом пробросить GPU в контейнер было использование --runtime=nvidia вместе с NVIDIA_VISIBLE_DEVICES. В Docker 19.03 добавили флаг --gpus и полноценный API для запроса устройств. Compose адаптировался дольше, и когда это произошло, запрос устройства был реализован через deploy.resources.reservations.devices — ключ, который большинство пользователей привыкли игнорировать, так как deploy раньше относился к Docker Swarm.

В результате сегодня работают оба варианта, а в опубликованном примере Jellyfin используются оба одновременно. Наличие runtime: nvidia ничего не стоит и позволяет файлу работать в старых версиях Compose. Если вы оставите только runtime: nvidia и удалите блок deploy, вы обязаны сохранить NVIDIA_VISIBLE_DEVICES=all, так как этот устаревший путь считывает переменную окружения для определения того, какие устройства нужно внедрить, и не имеет альтернативного API для запроса устройств.

Включение аппаратного транскодирования NVIDIA в Jellyfin

На данный момент 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, что выглядит так, будто проброс не работает.

Существует еще одно ограничение для всей страницы: аппаратное ускорение работает только с комплектной сборкой jellyfin-ffmpeg. Если вы укажете путь FFmpeg к системному FFmpeg, вы получите частичное ускорение или его отсутствие.

Какие кодеки поддерживает ваше поколение GPU для декодирования и кодирования

Это границы, установленные Jellyfin для NVENC и NVDEC. Декодирование и кодирование — это разные возможности, и карта может обладать одной из них, не имея другой.

• H.264 8-bit: любой GPU NVIDIA с NVENC и NVDEC поддерживает как декодирование, так и кодирование.
• HEVC 8-bit: декодирование и кодирование начиная с архитектуры Maxwell второго поколения (GM206) и новее.
• HEVC 10-bit: декодирование начиная с Maxwell второго поколения и новее, но кодирование — только с архитектуры Pascal и новее.
• AV1: декодирование начиная с Ampere и новее, кодирование — с Ada Lovelace и новее.

Разделение в поддержке HEVC 10-bit — это то, с чем чаще всего приходится сталкиваться на практике. Карта эпохи Maxwell декодирует ваш 4K HDR файл на GPU, но не может закодировать 10-битный вывод, поэтому Jellyfin выполняет перекодирование в 8-битный H.264. Это работает, и в большинстве случаев такой выбор является верным для клиентов. Кодирование в AV1 редко бывает нужным в 2026 году, независимо от вашей карты, так как поддержка декодирования AV1 на стороне клиента всё ещё ограничена, а транскодирование обычно требуется для тех клиентов, которые и так испытывали трудности с воспроизведением.

Почему тональная компрессия незаметно перегружает GPU

Тональная компрессия (tone mapping) из HDR (high dynamic range) в SDR (standard dynamic range) — это настройка, которая исчерпывает ресурсы вашего GPU, и причина кроется в архитектуре. Декодирование выполняется на NVDEC. Кодирование — на NVENC. Тональная компрессия не использует ни то, ни другое: это CUDA-фильтр, работающий на шейдерных ядрах, то есть на той же универсальной части GPU, которая выполняет вычислительные задачи. Таким образом, поток 4K HDR, требующий тональной компрессии, задействует декодер, кодировщик и дополнительно нагружает шейдеры.

Jellyfin указывает, что CUDA-тональная компрессия доступна на любом GPU NVIDIA, способном декодировать HEVC 10-bit. Это означает, что флажок появляется и работает на картах, которые не справляются с этой задачей в разрешении 4K. Симптомом является поток, который запускается, постоянно буферизируется и не воспроизводится плавно, в то время как nvidia-smi показывает, что кодировщик почти не загружен.

Именно поэтому стоит отдельно отслеживать нагрузку на шейдеры.

nvidia-smi dmon -s u

Эта команда выводит одну строку в секунду с отдельными столбцами для sm, enc и dec. Низкие показатели enc и dec при высоком значении sm означают, что специализированные блоки простаивают, а узким местом являются шейдеры. Следовательно, ресурсы расходуются на тональную компрессию, масштабирование или вжигание субтитров. CUDA-путь также поддерживает Dolby Vision profile 5 с использованием zero copy. Это важно, так как без 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 года, а не результаты наших собственных измерений. Для любой карты GeForce установлено ограничение в 12 одновременных сессий кодирования, независимо от модели. Этот лимит реализован на уровне драйвера, а не на аппаратном уровне, и NVIDIA уже несколько раз повышала его за прошедшие годы, поэтому всегда сверяйтесь с актуальной матрицей, а не со старыми темами на форумах. Количество движков — это параметр, который действительно зависит от модели карты: GeForce RTX 5090 оснащена 3 движками NVENC, в то время как GeForce RTX 4060 имеет 1. Большее количество движков увеличивает пропускную способность параллельного кодирования, но не повышает лимит сессий.

Ограничение распространяется именно на сессии кодирования, поэтому оно учитывает только потоки транскодирования. Прямое воспроизведение (direct play) и ремуксинг не открывают сессию кодирования. В той же матрице указано, что для карт дата-центров, таких как L4, ограничений нет; именно такие GPU обычно предоставляются в рамках планов VPS, поэтому данный лимит актуален преимущественно для домашних серверов.

При достижении лимита транскодирование завершается с ошибкой, а в логе FFmpeg появляется OpenEncodeSessionEx failed: out of memory (10). Сообщение указывает на нехватку памяти, но отказ из-за превышения лимита сессий возвращает тот же код, поэтому сначала проверьте количество одновременных потоков, прежде чем искать утечку VRAM. На практике большинство пользователей упираются в предел производительности при тональной компрессии (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 внутри контейнера обычно показывает пустой список процессов, так как он не видит PID вне своего пространства имен, при этом показатели загрузки отображаются корректно. Пустой список процессов внутри контейнера не является ошибкой.

Когда происходит незаметный переход на программное декодирование

Jellyfin стремится продолжать воспроизведение. Если аппаратный путь недоступен, система переключается на программную обработку вместо остановки потока. Поэтому индикатором проблемы служит нагрузка на CPU и лог FFmpeg, а не сообщение об ошибке.

Cannot load libnvcuvid.so.1 в логе транскодирования означает, что библиотека декодера не была смонтирована в контейнер. Установите NVIDIA_DRIVER_CAPABILITIES=all и пересоздайте контейнер, так как изменение переменных окружения требует docker compose up -d для пересборки, а обычный перезапуск сохраняет старые настройки.

No capable devices found из h264_nvenc означает, что FFmpeg обратился к библиотеке кодировщика, но не обнаружил доступную карту. Проверьте docker compose exec jellyfin nvidia-smi еще раз, так как это обычно указывает на то, что резервирование устройства было сброшено или контейнер был пересоздан из устаревшего файла конфигурации.

Высокая нагрузка на CPU при бездействующем GPU означает, что декодирование завершается с ошибкой без вывода уведомлений. Снимите галочки с кодеков, которые не поддерживаются вашим поколением оборудования, затем снова запустите тот же файл и изучите лог FFmpeg, чтобы увидеть, появится ли -hwaccel cuda.

Если транскодирование 4K HDR запускается и зависает, а 1080p работает нормально, значит, достигнут предел возможностей тональной компрессии (tone-mapping), а не произошел сбой установки. Проверьте это по столбцу sm в nvidia-smi dmon -s u, после чего либо снизьте запрашиваемое клиентом разрешение, либо используйте 4K HDR файлы только на клиентах, поддерживающих прямое воспроизведение (direct play).

FAQ

Почему Jellyfin продолжает использовать CPU после включения NVENC?

Проверьте самый свежий лог FFmpeg.Transcode в разделе Dashboard, затем Logs. Если там указано libx264, значит, аппаратный путь не использовался вовсе. Обычно это означает, что контейнер не видит GPU, поэтому выполните docker compose exec jellyfin nvidia-smi для проверки. Если отображается h264_nvenc, но CPU всё равно загружен, значит, декодирование выполняется программно. Это происходит, если вы выбрали кодек, который ваша карта не поддерживает, или если опция Enable hardware encoding была выключена, из-за чего на GPU перенесена только часть конвейера.

Нужно ли по-прежнему указывать строку runtime: nvidia в Docker Compose?

Нет, если у вас есть блок deploy.resources.reservations.devices и актуальная версия Docker Compose. Этот блок является современным способом запроса устройств и выполняет ту же задачу. runtime: nvidia — это старый путь из эпохи nvidia-docker2; он всё ещё работает, и в официальном примере Jellyfin сохранены оба варианта. Наличие обоих вариантов безопасно. Если оставить только runtime: nvidia, вы обязаны сохранить и NVIDIA_VISIBLE_DEVICES=all, так как этот путь не содержит запроса устройства и считывает список устройств из переменных окружения.

Сколько потоков может одновременно транскодировать одна видеокарта NVIDIA?

Согласно опубликованной NVIDIA матрице, по состоянию на август 2026 года для карт GeForce установлено ограничение в двенадцать одновременных сессий кодирования, а для карт дата-центров лимиты не указаны. Однако обычно вас ограничивает не этот предел. Tone mapping из HDR в SDR выполняется на шейдерных ядрах, а не на NVENC, поэтому несколько потоков 4K HDR исчерпают ресурсы шейдеров задолго до того, как счетчик сессий станет критичным. Оцените свой случай с помощью nvidia-smi dmon -s u и следите за столбцом sm, а не за количеством сессий.

Можно ли использовать аппаратное транскодирование на VPS без GPU?

Нет. Для кодирования необходим физический блок NVENC, а lspci -nn | grep -Ei "3d|display|vga" на стандартном VPS показывает только виртуальный графический адаптер гипервизора. Реалистичный вариант на тарифе без GPU — исключить транскодирование: установите в настройках клиента качество Auto, используйте нативное клиентское приложение вместо браузера и конвертируйте графические субтитры в текстовые, чтобы они не вызывали принудительное перекодирование видео.

Почему 4K HDR тормозит, а 1080p транскодируется нормально?

Эти две задачи используют разные части видеокарты. Транскодирование 1080p SDR — это только декодирование и кодирование, оба процесса выполняются на специализированном аппаратном обеспечении. Поток 4K HDR добавляет tone mapping — это CUDA-фильтр, работающий на шейдерных ядрах, плюс масштабирование кадра гораздо большего размера. Если nvidia-smi dmon -s u показывает низкие значения enc и dec при высоком sm, это подтверждает, что специализированные блоки простаивают, а пределом производительности являются универсальные ядра.