Jellyfin Desktop: A Powerful Cross-Platform Client with Embedded MPV Player

This article answers the core question: What is Jellyfin Desktop, how does it differ from other Jellyfin clients, and why should media server enthusiasts use it—plus detailed guides on installation and building from source?

Jellyfin Desktop is a cross-platform desktop client that combines the familiar jellyfin-web interface with an embedded MPV player. It supports Windows, macOS, and Linux, allowing media to play directly within the same window—unlike traditional setups where playback opens in a separate player. A key feature is full audio passthrough support, making it ideal for high-quality home theater setups.

Jellyfin Desktop playback interface screenshot
Image source: Project official repository

Why Choose Jellyfin Desktop?

This section answers the core question: What makes Jellyfin Desktop stand out compared to the web client or other official players?

The real value of Jellyfin Desktop lies in its seamless integration of the jellyfin-web UI with MPV’s robust playback engine. Imagine watching a 4K HDR movie with Dolby Atmos audio: the video stays embedded in the browser-like interface, so you can browse your library, adjust subtitles, or switch tracks without interrupting immersion. MPV handles hardware acceleration and audio passthrough effortlessly, passing high-bitrate formats like Dolby TrueHD directly to your AV receiver—something browser-based playback often struggles with.

In my experience, this embedded approach creates a more cohesive desktop experience, especially on large monitors or multi-display setups. It avoids the limitations of pure web playback while being lighter and more customizable than older dedicated clients.

Quick Download and Installation Options

This section answers the core question: How can you get started with Jellyfin Desktop quickly and easily?

The easiest way is downloading pre-built releases or using package managers.

  • Official Releases (Windows, macOS, Linux):
    Available at: https://github.com/jellyfin/jellyfin-desktop/releases
    Note for macOS: Intel builds require macOS 12+, Apple Silicon requires macOS 14+.

  • Linux via Flathub:

    flatpak install flathub org.jellyfin.JellyfinDesktop

    Flatpak provides a sandboxed, dependency-free experience—perfect for users who want zero hassle.

For most people testing media library management and playback, start with a release binary or Flatpak; it’s ready in minutes.

Building Jellyfin Desktop from Source on Linux

This section answers the core question: How do you build Jellyfin Desktop from source on Linux distributions like Ubuntu or Fedora for the latest features or customizations?

Building from source gives access to cutting-edge updates and is essential for contributors. Here’s how on popular distros.

Ubuntu-Based Systems

First, install dependencies:

sudo apt install autoconf automake build-essential cmake curl g++ git libasound2-dev libcec-dev libegl1-mesa-dev libfontconfig1-dev libfreetype6-dev libfribidi-dev libgl1-mesa-dev libgnutls28-dev libharfbuzz-dev libpulse-dev libsdl2-dev libtool libuchardet-dev libva-dev libvdpau-dev libx11-dev libxrandr-dev mesa-common-dev meson qml6-module-qtqml-workerscript qml6-module-qtquick-controls qml6-module-qtquick-templates qml6-module-qtquick-window qml6-module-qtwebchannel qml6-module-qtwebengine qml6-module-qtwebengine-controlsdelegates qml6-module-qtwebview qt6-base-private-dev qt6-webengine-private-dev unzip wget yasm zlib1g-dev

Full build process:

mkdir ~/jmp; cd ~/jmp
git clone https://github.com/mpv-player/mpv-build.git
cd mpv-build
./use-mpv-release
./update
echo -Dlibmpv=true > mpv_options
./rebuild -j$(nproc)
sudo ./install
sudo ln -s /usr/local/lib/x86_64-linux-gnu/libmpv.so /usr/local/lib/x86_64-linux-gnu/libmpv.so.1
sudo ln -sf /usr/local/lib/x86_64-linux-gnu/libmpv.so /usr/local/lib/libmpv.so.2
sudo ldconfig

cd ~/jmp/
git clone --recursive https://github.com/jellyfin/jellyfin-desktop.git
cd jellyfin-desktop
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/usr/local/ -G Ninja ..
ninja
sudo ninja install
rm -rf ~/jmp/

Once built, you have a fully MPV-integrated client ready for high-performance playback.

Fedora-Based Systems

Dependencies:

sudo dnf install autoconf automake libtool freetype-devel libXrandr-devel libvdpau-devel libva-devel mesa-libGL-devel libdrm-devel libX11-devel mesa-libEGL-devel yasm alsa-lib pulseaudio-libs-devel zlib-devel fribidi-devel git gnutls-devel mesa-libGLU-devel SDL2-devel cmake wget g++ qt-devel libcec-devel qt6-qtbase-devel curl unzip qt6-qtwebchannel-devel qt6-qtwebengine-devel mpv.x86_64 qt6-qtbase.x86_64 meson.noarch ninja-build.x86_64 qt6-qtbase-private-devel mpv-libs.x86_64 mpv-devel qt6-qtdeclarative nasm libatomic libshaderc mpvqt-devel

Build commands (note path differences):

mkdir ~/jmp; cd ~/jmp
git clone https://github.com/mpv-player/mpv-build.git
cd mpv-build/
echo -Dlibmpv=true > mpv_options
echo -Dpipewire=disabled >> mpv_options  # Temporary to avoid crashes
./rebuild -j$(nproc)
sudo ./install
sudo mkdir /usr/local/lib/x86_64-linux-gnu
sudo ln -s /usr/local/lib64/libmpv.so /usr/local/lib/x86_64-linux-gnu/libmpv.so.1
sudo ln -s /usr/local/lib64/libmpv.so /usr/local/lib/x86_64-linux-gnu/libmpv.so
sudo ldconfig

cd ~/jmp/
git clone --recursive https://github.com/jellyfin/jellyfin-desktop.git
cd jellyfin-desktop/
mkdir build
cd build/
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/usr/local/ ..
make -j$(nproc)
sudo make install

Reflection: The symbolic link steps on Fedora highlight distribution differences, but mastering them deepens your understanding of Linux library management.

Building on Windows

This section answers the core question: How do Windows users compile Jellyfin Desktop from source?

Windows builds require several tools but yield native installers.

Required installations:

  • CMake (add to PATH)
  • Ninja (place in build directory)
  • Qt 6 (select MSVC 2019 64-bit and Qt WebEngine)
  • Visual Studio 2019 Build Tools
  • libmpv (place in mpv subfolder, rename/organize files)
  • WiX Toolset v3.11

Run in Git Bash:

git clone --recursive https://github.com/jellyfin/jellyfin-desktop
cd jellyfin-desktop
mkdir build
cd build

Then in x64 Native Tools Command Prompt:

set PATH=%PATH%;C:\Program Files (x86)\WiX Toolset v3.11\bin
cmake -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=output -DCMAKE_MAKE_PROGRAM=ninja.exe -DQTROOT=C:/Qt/6.x.x/msvc2019_64 -DMPV_INCLUDE_DIR=mpv/include -DMPV_LIBRARY=mpv/libmpv-2.dll -DCMAKE_INSTALL_PREFIX=output ..
lib /def:mpv\mpv.def /out:mpv\mpv.dll.lib /MACHINE:X64
ninja
ninja windows_package

Great for users needing custom Windows packages.

Building on macOS

This section answers the core question: What’s the simplest way to build Jellyfin Desktop on macOS?

macOS builds are straightforward with Homebrew.

Install Qt 6 (include Qt WebEngine), then:

brew install mpv ninja qt

git clone --recursive https://github.com/jellyfin/jellyfin-desktop.git
cd jellyfin-desktop

cmake -B build -G Ninja -DUSE_STATIC_MPVQT=ON
cmake --build build

The clean command-line flow reminds me why many prefer macOS for development.

Configuration and Log Locations

This section answers the core question: Where are config and log files stored for troubleshooting or customization?

The main config is jellyfin-desktop.conf; add mpv.conf for direct MPV tweaks.

Platform Config Directory Log Directory
Windows %LOCALAPPDATA%\Jellyfin Desktop\ %LOCALAPPDATA%\Jellyfin Desktop\logs
Linux ~/.local/share/jellyfin-desktop/ ~/.local/share/jellyfin-desktop/logs/
Linux (Flatpak) ~/.var/app/org.jellyfin.JellyfinDesktop/data/jellyfin-desktop/ Same as config
macOS ~/Library/Application Support/Jellyfin Desktop/ ~/Library/Logs/Jellyfin Desktop/

Logs are invaluable for diagnosing playback issues quickly.

Enabling Web Developer Tools

This section answers the core question: How to access browser dev tools for interface debugging?

Launch with:

--remote-debugging-port=9222

Then in Chrome/Chromium: chrome://inspect/#devices (configure localhost:9222).

Essential for tweaking the jellyfin-web experience.

License and Known Issues

Licensed under GPL v2. View dependencies with --licenses.

Known issue: When building MPV from source, disable pipewire to prevent crashes.

Quick Start Checklist

  1. Download from GitHub Releases or install via Flatpak.
  2. For latest features, build from source (platform-specific guides).
  3. Edit jellyfin-desktop.conf or add mpv.conf in user data directory.
  4. Use --remote-debugging-port=9222 for web debugging.
  5. Check logs for issues.

One-Page Summary

Jellyfin Desktop = jellyfin-web + embedded MPV
Key Benefits: In-window playback, audio passthrough, cross-platform
Install: GitHub Releases / Flathub
Build: Compile libmpv first, then client
Config/Logs: Standard per-platform directories
Debugging: Remote port 9222
License: GPL v2

Frequently Asked Questions (FAQ)

  1. How does Jellyfin Desktop differ from the official Jellyfin Media Player?
    It embeds playback in the web interface; older clients use separate windows.

  2. Is audio passthrough supported by default?
    Yes, thanks to MPV—perfect for advanced formats like DTS-HD.

  3. What are the macOS version requirements?
    Intel: macOS 12+, Apple Silicon: macOS 14+.

  4. Why disable pipewire when building MPV?
    It can cause segmentation faults in self-built versions.

  5. How to view dependency licenses?
    Run with --licenses or check resources/misc/licenses.txt.

  6. What are the config files called? Can I customize MPV?
    Main: jellyfin-desktop.conf; add mpv.conf in the same directory.

  7. How to enable browser developer tools?
    Start with --remote-debugging-port=9222 and use Chrome’s inspect page.

  8. Why is WiX needed for Windows builds?
    For generating the Windows installer package.