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.

Installation

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

{
  services.jellyfin.enable = true;
  environment.systemPackages = [
    pkgs.jellyfin
    pkgs.jellyfin-web
    pkgs.jellyfin-ffmpeg
  ];
}

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.

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.

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