Skip to main content

HWA Tutorial On NVIDIA GPU

This tutorial guides you on setting up full video hardware acceleration on NVIDIA GPU via NVENC.

Acceleration Methods​

Hardware accelerated transcoding is supported on NVIDIA GPUs since Maxwell architecture.

On Windows and Linux NVENC is the only available method.

The NVENC/NVDEC are the proprietary video codec APIs of NVIDIA GPUs, which can be used with CUDA to achieve full hardware acceleration.

caution

Consumer targeted Geforce and some entry-level Quadro cards have an artificial limit on the number of concurrent NVENC encoding sessions. This restriction can be circumvented by applying an unofficial patch to the NVIDIA Linux and Windows driver.

NVIDIA driverNVENC concurrent sessions
550 and newerUp to 8 encoding sessions
530 to 546Up to 5 encoding sessions
pre-530Up to 3 encoding sessions
note

NVENC supports headless server on both Windows and Linux, which means a connected monitor is not required.

Tone-mapping Methods​

Hardware accelerated HDR/DV to SDR tone-mapping is supported on all NVIDIA GPUs that have HEVC 10-bit decoding.

On Windows and Linux CUDA is the only available tone-mapping method. It also supports Dolby Vision P5 and zero-copy.

note

The Enable enhanced NVDEC decoder feature toggles between the newer NVDEC and the older CUVID decoding processes. Dolby Vision support requires that this option be checked in order to enable NVDEC.

Select GPU Hardware​

For beginners, please refer to the Hardware Selection Guide for tips on selecting hardware. For expert users, please continue reading this section.

caution

Most NVIDIA GPUs come with NVENC/NVDEC support but some low-end and mobile models (e.g. GT1030 and MX450) are exceptions.

Video codec support can be checked via the NVIDIA GPU Codec Support Matrix prior to buying a GPU suitable for hardware acceleration.

Transcode H.264​

AVC / H.264 8-bit is still widely used due to its excellent compatibility. All NVIDIA GPUs supporting NVENC/NVDEC can decode and/or encode it.

  • Decoding & Encoding H.264 8-bit - Any NVIDIA GPU supporting NVENC/NVDEC

Transcode HEVC​

HEVC / H.265 remains the first choice for storing 4K 10-bit, HDR and Dolby Vision video. It has mature software encoding support thanks to x265, as well as the widely implemented hardware encoding support in most GPUs released after 2016.

Maxwell+ GPUs provide support for HEVC:

  • Decoding & Encoding HEVC 8-bit - Maxwell 2nd Gen (GM206) and newer

  • Decoding HEVC 10-bit - Maxwell 2nd Gen (GM206) and newer

  • Encoding HEVC 10-bit - Pascal and newer

note

Note that in Maxwell 2nd Gen series only the GM206 variants provide HEVC 10-bit decoding support. Its sucessor Pascal has full support for HEVC 10-bit and improved speed and quality.

Transcode AV1​

AV1 is a royalty-free, future-proof video codec. It saves a lot of storage space and network bandwidth due to smaller file size. The downside is that decoding and encoding is very demanding on the CPU. Hardware acceleration makes it possible to transcode AV1 streams on the fly. AV1 encoding is supported in Jellyfin 10.9 and newer.

NVIDIA added support for AV1 acceleration in their latest GPUs:

  • Decoding AV1 8/10-bit - Ampere and newer

  • Encoding AV1 8/10-bit - Ada Lovelace and newer

Transcode Other Codecs​

Please refer to these links:

Speed And Quality​

Encoding quality:

  • H.264 & HEVC - Ada/Ampere/Turing > Turing TU117/Volta/Pascal > Maxwell

  • AV1 - Ada Lovelace only

Decoding & Encoding speed within the same generation:

  • Multiple NVENC/NVDEC models > Single NVENC/NVDEC models

  • High GPU clock speed models > Low GPU clock speed models

  • High memory bandwidth models > Low memory bandwidth models

NVENC/NVDEC performance tables:

Windows Setups​

Windows 10 64-bit and newer is recommeded. In Jellyfin 10.8 the minimum required NVIDIA driver version is 471.41.

Configure On Windows Host​

  1. Wipe the old driver with DDU if you upgraded from a pre-Maxwell NVIDIA GPU without doing a fresh installation.

  2. Clean install the latest driver from NVIDIA Driver Downloads.

  3. Enable NVENC in Jellyfin and uncheck the unsupported codecs.

Configure With Windows Virtualization​

NVIDIA Windows driver provides access to the NVENC/NVDEC and CUDA in Windows WSL2 and Docker.

Refer to Configure On Linux Host and Configure With Linux Virtualization.

Verify On Windows​

  1. Play a video in the Jellyfin web client and trigger a video transcoding by setting a lower resolution or bitrate.

  2. Open the "Task Manager" and navigate to the GPU page.

  3. Check the occupancy of the engines as follows.

    • 3D - 2D/3D engine or CUDA/GPGPU workload

    • Copy - Blitter/Copy engine workload

    • Video Decode - Video decoder workload

    • Video Encode - Video encoder workload

    • Cuda - CUDA/GPGPU workload

    Verify NVIDIA On Windows

Linux Setups​

A 64-bit Linux distribution is required. In Jellyfin 10.8 the minimum required NVIDIA driver version is 470.57.02.

Configure On Linux Host​

Debian And Ubuntu Linux​

The jellyfin-ffmpeg5 deb package required by Jellyfin 10.8 doesn't include any NVIDIA proprietary driver.

You have to install the NVIDIA driver from the distro and configure the the permission of the jellyfin user.

note

Root permission is required.

  1. Assuming you have added the jellyfin repository to your apt source list and installed the jellyfin-server and jellyfin-web.

  2. Install the jellyfin-ffmpeg5 package. Remove the deprecated jellyfin meta package if it breaks the dependencies:

    sudo apt update && sudo apt install -y jellyfin-ffmpeg5

  3. Install the NVIDIA proprietary driver by following these links. Then install two extra packages for NVENC and NVDEC support:

  4. Check the NVIDIA GPU status by using nvidia-smi:

    $ nvidia-smi

    +-----------------------------------------------------------------------------+
    | NVIDIA-SMI 470.161.03   Driver Version: 470.161.03   CUDA Version: 11.4     |
    |-------------------------------+----------------------+----------------------+
    | GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
    | Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
    |                               |                      |               MIG M. |
    |===============================+======================+======================|
    |   0  NVIDIA GeForce ...  Off  | 00000000:1C:00.0 Off |                  N/A |
    |  0%   44C    P0    N/A /  75W |      0MiB /  1998MiB |      0%      Default |
    |                               |                      |                  N/A |
    +-------------------------------+----------------------+----------------------+
    ...

  5. Enable NVENC in Jellyfin and uncheck the unsupported codecs.

Linux Mint​

Linux Mint uses Ubuntu as its package base.

You can follow the configuration steps of Debian And Ubuntu Linux but install all Jellyfin packages jellyfin-server, jellyfin-web and jellyfin-ffmpeg5 manually from the Jellyfin Server Releases Page. Also make sure you choose the correct codename by following the official version maps.

Arch Linux​

note

Root permission is required.

  1. Install the Archlinux/extra jellyfin-ffmpeg package:

    sudo pacman -Syu jellyfin-ffmpeg

  2. Install the NVIDIA proprietary driver by following the link. Then install an extra package for NVENC and NVDEC support:

    sudo pacman -Syu nvidia-utils

  3. Check the NVIDIA GPU status by using nvidia-smi:

    nvidia-smi

  4. Enable NVENC in Jellyfin and uncheck the unsupported codecs.

Other Distros​

We provide portable jellyfin-ffmpeg binaries for distros that don't have a regular maintainer.

They can be downloaded from one of these links:

note

Minimum requirements for glibc and Linux versions:

  • x86_64 / amd64 - glibc >= 2.23, Linux >= 4.4 (most distros released in 2016 and later)

Extract and install it to the correct path, change the FFmpeg path in the Jellyfin dashboard to match it:

note

Root permission is required.

cd ~/
mkdir -p jellyfin-ffmpeg
wget https://repo.jellyfin.org/releases/ffmpeg/<VERSION>/jellyfin-ffmpeg_<VERSION>_portable_linux64-gpl.tar.xz
tar -xvf jellyfin-ffmpeg_<VERSION>_portable_linux64-gpl.tar.xz -C jellyfin-ffmpeg
sudo mv jellyfin-ffmpeg /usr/lib
sudo ldd -v /usr/lib/jellyfin-ffmpeg/ffmpeg

Install the NVIDIA proprietary driver packages and their dependencies that contain these key words:

  • NVIDIA NVDEC CUVID - DECODE

  • NVIDIA NVENC - ENCODE

Configure With Linux Virtualization​

Official Docker​

The official Docker image doesn't include any NVIDIA proprietary driver.

You have to install the NVIDIA driver and NVIDIA Container Toolkit on the host system to allow Docker access to your GPU.

note

Root permission is required.

  1. Install the NVIDIA proprietary driver on the host system. See above instructions.

  2. Install the NVIDIA Container Toolkit on the host system by following this link:

  3. Use the Docker command line or docker-compose:

    • Example command line:

      docker run -d \
       --name=jellyfin \
       --volume /path/to/config:/config \
       --volume /path/to/cache:/cache \
       --volume /path/to/media:/media \
       --user 1000:1000 \
       --net=host \
       --restart=unless-stopped \
       --runtime=nvidia \
       --gpus all \
       jellyfin/jellyfin

    • Example docker-compose (version 3) configuration file written in YAML:

      version: '3'
      services:
        jellyfin:
          image: jellyfin/jellyfin
          user: 1000:1000
          network_mode: 'host'
          volumes:
            - /path/to/config:/config
            - /path/to/cache:/cache
            - /path/to/media:/media
          runtime: nvidia
          deploy:
            resources:
              reservations:
                devices:
                  - capabilities: [gpu]
    note

    If you encounter the upsteam issue CUDA_ERROR_NO_DEVICE: no CUDA-capable device is detected, pass these extra devices to the Docker:

    /dev/nvidia-caps:/dev/nvidia-caps
    /dev/nvidia0:/dev/nvidia0
    /dev/nvidiactl:/dev/nvidiactl
    /dev/nvidia-modeset:/dev/nvidia-modeset
    /dev/nvidia-uvm:/dev/nvidia-uvm
    /dev/nvidia-uvm-tools:/dev/nvidia-uvm-tools

  4. Add your username to the video group:

    sudo usermod -aG video $USER

  5. Update dynamic links and restart the Docker service:

    docker exec -it jellyfin ldconfig
    sudo systemctl restart docker

  6. Check the NVIDIA GPU's status by using nvidia-smi:

    docker exec -it jellyfin nvidia-smi

  7. For trying out the unstable build, change jellyfin/jellyfin to jellyfin/jellyfin:unstable on your own risk.

  8. Enable NVENC in Jellyfin and uncheck the unsupported codecs.

note

Note that the official Jellyfin Docker image already sets the required environment variables for NVIDIA GPUs. If you are building your own image don't forget the add two extra environment variables into the Docker configs.

  • NVIDIA_DRIVER_CAPABILITIES=all

  • NVIDIA_VISIBLE_DEVICES=all

Linuxserver.io Docker​

LSIO Docker images are maintained by linuxserver.io, please refer their docs from GitHub - linuxserver/docker-jellyfin.

note

The paths of Jellyfin config and data folders in the official and LSIO Docker images are different. So they cannot be easily exchanged.

Other Virtualizations​

Other Virtualizations are not verified and may or may not work on NVIDIA GPU.

Refer to the HWA Tutorial On Intel GPU - Configure With Linux Virtualization for more information.

Verify On Linux​

  1. Play a video in the Jellyfin web client and trigger a video transcoding by setting a lower resolution or bitrate.

  2. Use nvidia-smi command to check the occupancy of the NVIDIA GPU and the VRAM usage of each jellyfin-ffmpeg process:

    $ nvidia-smi

    +-----------------------------------------------------------------------------+
    | NVIDIA-SMI 470.161.03   Driver Version: 470.161.03   CUDA Version: 11.4     |
    |-------------------------------+----------------------+----------------------+
    | GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
    | Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
    |                               |                      |               MIG M. |
    |===============================+======================+======================|
    |   0  NVIDIA GeForce ...  Off  | 00000000:1C:00.0 Off |                  N/A |
    | 43%   44C    P2    36W /  75W |    274MiB /  1998MiB |     68%      Default |
    |                               |                      |                  N/A |
    +-------------------------------+----------------------+----------------------+
    +-----------------------------------------------------------------------------+
    | Processes:                                                                  |
    |  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
    |        ID   ID                                                   Usage      |
    |=============================================================================|
    |    0   N/A  N/A      4024      G   /usr/lib/xorg/Xorg                 63MiB |
    |    0   N/A  N/A      5837      C   /usr/lib/jellyfin-ffmpeg/ffmpeg   195MiB |
    +-----------------------------------------------------------------------------+