Jellyfin

Jellyfin

Media server Application

Developer(s)	Jellyfin Project
Operating System	Cross-platform (Linux, macOS, Windows)
Platform(s)	Server
Language(s)	C#
License	GPL-2.0
External links
Website	jellyfin.org
GitHub	jellyfin/jellyfin
Bug tracker	GitHub Issues
Documentation	jellyfin.org/docs

Jellyfin is a free and open-source media server that enables users to manage and stream their personal media libraries across various devices. It consists of the Jellyfin Server and multiple client applications including Jellyfin Media Player and a web interface.

Client Installation

Jellyfin is available both via the web interface, and through a desktop application.

If you would like to install the desktop application, use the following:

⚠︎

Warning: Currently in NixOS 25.11, jellyfin-desktop 2.0 on nixpkgs is unsupported (and no longer available on their release page) as it relies on an out-of-date QT engine. This can cause rapid, bright flashes when playing video on Wayland, which is a serious seizure risk (see this issue).

The easiest fixes are:

• Use the web player.
• Run from the CLI with: `QT_QPA_PLATFORM=xcb jellyfin-desktop > /dev/null 2>&1 & disown`
• Create a launch script your app launcher can find as explained for vicinae here.

{
  environment.systemPackages = [
    pkgs.jellyfin-desktop
  ];
}

Alternatively, you can use the Jellyfin web client by using your preferred web browser to visit the server directly. See below on how to install the Jellyfin server.

Server Installation

To enable Jellyfin on NixOS, add the service configuration to your /etc/nixos/configuration.nix file:

{
  services.jellyfin.enable = true;
}

For more advanced configuration options, refer to the NixOS options documentation:

{
  services.jellyfin = {
    enable = true;
    openFirewall = true;
  };
}

After configuring Jellyfin, rebuild your system for the changes to take effect:

$ sudo nixos-rebuild switch

After the rebuild completes, verify that Jellyfin is running:

$ sudo systemctl status jellyfin

If Jellyfin is not running, you can start it manually:

$ jellyfin

Once Jellyfin is running, you can access the web interface:

• The Jellyfin server runs on port 8096 by default.
• Navigate to http://localhost:8096 for local access.
• For remote access, replace localhost with the server's IP address.

Configuration

Allowing access to external drives

Desktop environments typically mount external drives for the current user, while Jellyfin runs as the system user jellyfin by default. This can cause permission issues when accessing external media.

The simplest solution is to change the service user:

{
  services.jellyfin = {
    enable = true;
    openFirewall = true;
    user = "yourusername";
  };
}

If you change the user after Jellyfin is already installed, update the ownership of the data and cache directories:

$ sudo chown -R yourusername:yourusername /var/lib/jellyfin
$ sudo chown -R yourusername:yourusername /var/cache/jellyfin

Then restart the service:

$ sudo systemctl restart jellyfin

Alternatively, configure explicit mounts via Filesystems. This approach requires more setup and each drive must be declared, but provides finer control over what Jellyfin can access.

Hardware transcoding

Modern hardware often includes video acceleration capabilities that can significantly reduce CPU usage during transcoding. For detailed information, see the official Jellyfin documentation.

GPU Identification

If a computer with multiple GPUs is being configured, such as a laptop with a discrete GPU, selecting the correct GPU by path may be difficult. The paths in question are at /dev/dri. There will be several entries within this directory:

• /dev/dri/card*

2D graphics accelerators, these are not relevant to Jellyfin.

• /dev/dri/renderD*

3D graphics accelerators. These are what Jellyfin uses. Often /dev/dri/renderD128 and sequentially increasing from there.

• /dev/dri/by-path

A directory that contains symlinks to the above devices, but with their PCI bus IDs. This will be used for identification.

To identify, run lspci. This will most likely need to be downloaded, and is included in the package pciutils. This will show all devices on the PCI bus. For example:

00:00.0 Host bridge: Intel Corporation Xeon E3-1200 v6/7th Gen Core Processor Host Bridge/DRAM Registers (rev 05)
00:01.0 PCI bridge: Intel Corporation 6th-10th Gen Core Processor PCIe Controller (x16) (rev 05)
00:02.0 VGA compatible controller: Intel Corporation Kaby Lake-H GT2 [HD Graphics 630] (rev 04)
00:14.0 USB controller: Intel Corporation 100 Series/C230 Series Chipset Family USB 3.0 xHCI Controller (rev 31)
00:14.2 Signal processing controller: Intel Corporation 100 Series/C230 Series Chipset Family Thermal Subsystem (rev 31)
00:15.0 Signal processing controller: Intel Corporation 100 Series/C230 Series Chipset Family Serial IO I2C Controller #0 (rev 31)
00:15.1 Signal processing controller: Intel Corporation 100 Series/C230 Series Chipset Family Serial IO I2C Controller #1 (rev 31)
00:16.0 Communication controller: Intel Corporation 100 Series/C230 Series Chipset Family MEI Controller #1 (rev 31)
00:17.0 SATA controller: Intel Corporation HM170/QM170 Chipset SATA Controller [AHCI Mode] (rev 31)
00:1c.0 PCI bridge: Intel Corporation 100 Series/C230 Series Chipset Family PCI Express Root Port #3 (rev f1)
00:1c.3 PCI bridge: Intel Corporation 100 Series/C230 Series Chipset Family PCI Express Root Port #4 (rev f1)
00:1f.0 ISA bridge: Intel Corporation HM175 Chipset LPC/eSPI Controller (rev 31)
00:1f.2 Memory controller: Intel Corporation 100 Series/C230 Series Chipset Family Power Management Controller (rev 31)
00:1f.3 Audio device: Intel Corporation HM175/QM175/CM238 HD Audio Controller (rev 31)
00:1f.4 SMBus: Intel Corporation 100 Series/C230 Series Chipset Family SMBus (rev 31)
01:00.0 VGA compatible controller: NVIDIA Corporation GP106M [GeForce GTX 1060 Mobile] (rev a1)
01:00.1 Audio device: NVIDIA Corporation GP106 High Definition Audio Controller (rev a1)
02:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32)
03:00.0 Unassigned class [ff00]: Realtek Semiconductor Co., Ltd. RTL8411B PCI Express Card Reader (rev 01)
03:00.1 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168/8211/8411 PCI Express Gigabit Ethernet Controller (rev 12)

The beginning of each line denotes the device's PCI bus ID. Note this for the GPU desired, and add this device to your Jellyfin configuration via the /dev/dri/by-path directory. In this example, the Nvidia 1060M is added to the config. It can also be added to the config by inspecting the by-path symlink with realpath and using the canonical path.

{
  services.jellyfin = {
    enable = true;
    hardwareAcceleration = {
      enable = true;
      type = "nvenc";
      device = "/dev/dri/by-path/pci-0000:01:00.0-render";
    };
}

NVENC

Nvidia GPU's use NVENC for hardware encoding. To use this, CUDA must be enabled:

{
  nix.settings = {
    substituters = [
      "https://cache.flox.dev"
    ];
    trusted-public-keys = [
      "flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs="
    ];
  };
  nixpkgs.config.cudaSupport = true;

  services.jellyfin = {
    enable = true;
    hardwareAcceleration = {
      enable = true;
      type = "nvenc";
      device = "/dev/dri/renderD128";
    };
  };
}

For configuring the services.jellyfin.transcoding.hardwareDecodingCodec and services.jellyfin.transcoding.hardwareDecodingCodec options for Nvidia GPUs, consult the support matrix provided by Nvidia

VAAPI and Intel QSV

Intel GPUs support Video Acceleration API (VAAPI) and Quick Sync Video (QSV). The required packages must be added to hardware.graphics.extraPackages.

Choose the appropriate driver based on your CPU generation:

• intel-vaapi-driver for pre-Broadwell CPUs
• intel-media-driver for Broadwell and newer
• intel-compute-runtime for newer processors

Note: intel-media-sdk is deprecated and does not build on recent channels. Use VAAPI with intel-media-driver instead. See this discussion for details.

{ pkgs, lib, config, ... }:
{
  # Only set this if using intel-vaapi-driver:
  nixpkgs.config.packageOverrides = pkgs: {
    intel-vaapi-driver = pkgs.intel-vaapi-driver.override { enableHybridCodec = true; };
  };

  systemd.services.jellyfin.environment.LIBVA_DRIVER_NAME = "iHD"; # or i965 for older GPUs
  environment.sessionVariables = { LIBVA_DRIVER_NAME = "iHD"; };

  hardware.graphics = {
    enable = true;

    extraPackages = with pkgs; [
      intel-ocl # Generic OpenCL support

      # For Broadwell and newer (ca. 2014+), use with LIBVA_DRIVER_NAME=iHD:
      intel-media-driver

      # For older processors, use with LIBVA_DRIVER_NAME=i965:
      intel-vaapi-driver
      libva-vdpau-driver

      # For 13th gen and newer:
      intel-compute-runtime

      # For older processors:
      intel-compute-runtime-legacy1

      # For 11th gen and newer:
      vpl-gpu-rt

      # Deprecated (may not build on recent channels):
      # intel-media-sdk
    ];
  };

  services.jellyfin.enable = true;
}

Troubleshooting VAAPI and Intel QSV

Check supported VAAPI profiles:

$ nix-shell -p libva-utils --run vainfo

Verify OpenCL availability:

$ nix-shell -p clinfo --run clinfo

If clinfo shows Number of platforms 0, OpenCL is not enabled or available.

Monitor Intel GPU status:

$ nix-shell -p intel-gpu-tools --run intel_gpu_top

On Intel N100 CPUs, enable firmware loading to prevent GuC errors:

{
  hardware.enableAllFirmware = true;
}

Without this option, you may see errors like:

[    4.174843] i915 0000:00:10.0: [drm] *ERROR* GT0: GuC firmware i915/tgl_guc_70.bin: fetch failed -ENOENT
[    4.175621] i915 0000:00:10.0: [drm] GT0: GuC firmware(s) can be downloaded from https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/tree/i915
[    4.176350] i915 0000:00:10.0: [drm] *ERROR* GT0: GuC initialization failed -ENOENT
[    4.176977] i915 0000:00:10.0: [drm] *ERROR* GT0: Enabling uc failed (-5)
[    4.177502] i915 0000:00:10.0: [drm] *ERROR* GT0: Failed to initialize GPU, declaring it wedged!

VAAPI and Intel QSV on Arc GPU

Arc GPUs require Jellyfin to use FFmpeg compiled with vpl support. Use an overlay to override the FFmpeg configuration:

{ pkgs, ... }:
let
  jellyfin-ffmpeg-overlay = (final: prev: {
    jellyfin-ffmpeg = prev.jellyfin-ffmpeg.override {
      # Exact version depends on jellyfin-ffmpeg package
      # In 24.11 it's ffmpeg_7-full
      ffmpeg_7-full = prev.ffmpeg_7-full.override {
        withMfx = false; # Older media driver
        withVpl = true;  # New driver for Arc GPUs
        withUnfree = true;
      };
    };
  });
in
{
  nixpkgs.overlays = [ jellyfin-ffmpeg-overlay ];
}

This triggers a rebuild of the Jellyfin package. After applying, select "Intel QuickSync (QSV)" in the Jellyfin settings for hardware-accelerated transcoding with minimal CPU load.

On NixOS 25.11 and newer (specifically since this PR), vpl support in FFmpeg is enabled by default, so there is no need to use an overlay.

If your system has both integrated and discrete GPUs, manually select the QSV device in the Playback settings to avoid random device selection. Use intel_gpu_top -L to list available devices.

VAAPI with Jellyfin in a NixOS container

Containers do not inherit graphics drivers from the host system. When running Jellyfin in a NixOS container, replicate the hardware.graphics configuration and pass through the GPU devices (typically /dev/dri/card0 and /dev/dri/renderD128):

{
  allowedDevices = [
    { node = "/dev/dri/card0"; modifier = "rw"; }
    { node = "/dev/dri/renderD128"; modifier = "rw"; }
  ];

  bindMounts = {
    "/dev/dri/card0" = {
      hostPath = "/dev/dri/card0";
      isReadOnly = false;
    };
    "/dev/dri/renderD128" = {
      hostPath = "/dev/dri/renderD128";
      isReadOnly = false;
    };
  };

  config = {
    # Include hardware.graphics and services.jellyfin configuration
  };
}

Verify the configuration by adding libva-utils to the container's environment.systemPackages, logging in with machinectl shell container-name, and running vainfo. Successful output looks like:

Trying display: drm
libva info: VA-API version 1.22.0
libva info: Trying to open /run/opengl-driver/lib/dri/iHD_drv_video.so
libva info: Found init function __vaDriverInit_1_22
libva info: va_openDriver() returns 0
vainfo: VA-API version: 1.22 (libva 2.22.0)
vainfo: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 25.2.6 ()
vainfo: Supported profile and entrypoints
      VAProfileNone                   : VAEntrypointVideoProc
      VAProfileNone                   : VAEntrypointStats
      /* Additional profiles depend on your hardware */

With correct configuration, FFmpeg and Jellyfin can use hardware transcoding.

Tips and tricks

Intro Skipper plugin

The latest version of the Intro Skipper plugin from GitHub works without manual patches on Jellyfin web, Jellyfin Media Player, and Android TV clients.

If you need to manually patch the web interface for older versions, use an overlay:

nixpkgs.overlays = [
  (final: prev: {
    jellyfin-web = prev.jellyfin-web.overrideAttrs (finalAttrs: previousAttrs: {
      installPhase = ''
        runHook preInstall
        sed -i "s#</head>#<script src=\"configurationpage?name=skip-intro-button.js\"></script></head>#" dist/index.html
        mkdir -p $out/share
        cp -a dist $out/share/jellyfin-web
        runHook postInstall
      '';
    });
  })
];

Troubleshooting

Service not starting

If Jellyfin fails to start, check the service status:

$ sudo systemctl status jellyfin

Review the service logs for error messages:

$ sudo journalctl -u jellyfin -n 50

Cannot access media files

Verify that the Jellyfin user has read permissions for your media directories. Check file ownership and permissions:

$ ls -la /path/to/media

If using a custom user for the Jellyfin service, ensure the data directories have correct ownership as described in the configuration section.

See also

• Filesystems – Declarative filesystem mounting on NixOS
• Accelerated Video Playback – GPU acceleration configuration
• Intel Graphics – Intel GPU driver setup
• Overlays – Customizing packages with overlays
• NixOS options search – Jellyfin module options
• Jellyfin documentation – Official Jellyfin documentation