WINDOWS.md

Building Jellyfin Desktop on Windows

Quick Start

setup_build_deps.bat    # First time: download dependencies
build_windows.bat       # Build

Output: build\output\Jellyfin Desktop.exe

Prerequisites

• Visual Studio 2022/2026 with C++ tools
  • Install "MSVC v143 - VS 2022 C++ x64/x86 build tools" (required for Qt 6.10.1)
• Qt 6.10.1 MSVC 2022 64-bit at C:\Qt\6.10.1\msvc2022_64
• Build dependencies: Ninja, libmpv, VC++ redistributable

Directory Structure

• build_deps/ - External dependencies (persisted)
• build/ - Generated files (safe to delete)
• build_vs_debug/ - VS debug build

Scripts

• build_windows.bat - Release build + installer
• build_vs.bat - Debug build for Visual Studio
• setup_build_deps.bat - Download dependencies
• rebuild.bat - Quick rebuild

Clean Build

rmdir /s /q build
build_windows.bat

Debugging

build_vs.bat

Opens VS solution at build_vs_debug\jellyfin-desktop.sln

Requires Qt debug libraries (install via Qt Maintenance Tool).

Troubleshooting

Black Screen / GPU Issues

If the app opens but shows a black screen instead of the web interface:

1. Try software rendering (disables GPU acceleration):

   launch_software_mode.bat

   Or rebuild with the fix and run:

   "build\output\Jellyfin Desktop.exe" --software-rendering

2. Test different GPU configurations:

   try_gpu_workarounds.bat

   This interactive script tests various rendering modes to find what works.

3. Gather diagnostics:

   diagnose_black_screen.bat

   Collects logs, GPU info, and process details to diagnostics/ folder.

Common causes:

• Outdated GPU drivers
• Missing DirectX components
• Hardware acceleration incompatibility
• Older/unsupported graphics cards

Log Files

Application logs are located at:

%LOCALAPPDATA%\Jellyfin Desktop\logs\jellyfin-desktop.log

Notes

• Qt 6.10.1 requires VS 2022 toolset (v143) for ABI compatibility
• QtWebEngine resources auto-copied by build scripts
• Installer created after 5-second countdown (press key to skip)