Building Yuzu For Linux

This is meant for people who actually need to build Yuzu themselves like developers, tinkerers, or anyone doing low-level work. If you just want to run games, compiling from source is overkill. The official Linux AppImage runs fine as-is: download it, make it executable, and start playing.

However, if you want better control, debugging tools, custom build options, or you’re contributing to development, building Yuzu manually is the right choice.

Building Yuzu emulator from source on Linux using CMake, GCC, Qt, and Ninja
Compiling the Yuzu emulator from source on Linux using modern C++ toolchains and Qt

Before You Start

Yuzu is a modern C++ application and relies on C++20 features, which means your compiler and toolchain must be reasonably up to date.

Minimum Requirements

  • 64-bit Linux
  • GCC 11 or newer
  • Clang 14+ (required on some distros using GCC 12)
  • CMake 3.15 or newer
  • Ninja (recommended build system)
  • Qt 5.15+

If you’re building for ARM64, you must export:

VCPKG_FORCE_SYSTEM_BINARIES=1

Core Dependencies Explained

Some libraries are handled directly by Yuzu’s externals, meaning you don’t need to worry about version mismatches:

  • FFmpeg – video decoding and filters
  • SDL2 (2.0.18+) – controller input and window handling
  • opus – audio compression

Qt deserves special mention:

  • If Qt 5.15.2 is not found on your system, CMake will automatically download precompiled Qt binaries.
  • Qt WebEngine is optional but required for certain UI features.

Libraries Managed Automatically by vcpkg

Yuzu relies on vcpkg to pull in most of its third-party libraries for you, including:

Letting vcpkg handle this keeps the setup from turning into a distro-specific mess and helps sidestep the usual dependency conflicts.

Distribution-Specific Setup

Arch Linux / Manjaro

Arch users benefit from very up-to-date packages, making setup relatively painless.

sudo pacman -Syu --needed \
base-devel boost catch2 cmake ffmpeg fmt git glslang \
libzip lz4 mbedtls ninja nlohmann-json openssl opus \
qt5 sdl2 zlib zstd zip unzip

Notes:

  • GCC 11 or newer is mandatory.
  • If you want Qt WebEngine support, install qt5-webengine and pass the required include path when configuring CMake.

Ubuntu / Linux Mint / Debian

Supported versions:

  • Ubuntu 22.04+
  • Linux Mint 20+
  • Debian Bullseye or newer

Install dependencies:

sudo apt-get install \
autoconf cmake gcc-11 g++-11 git glslang-tools \
libasound2 libboost-context-dev libglu1-mesa-dev \
libhidapi-dev libpulse-dev libtool libudev-dev \
libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \
libxcb-render-util0 libxcb-xinerama0 libxcb-xkb1 \
libxext-dev libxkbcommon-x11-0 mesa-common-dev \
nasm ninja-build qtbase5-dev qtbase5-private-dev \
qtwebengine5-dev qtmultimedia5-dev \
libmbedtls-dev catch2 libfmt-dev liblz4-dev \
nlohmann-json3-dev libzstd-dev libssl-dev \
libavfilter-dev libavcodec-dev libswscale-dev

Important Ubuntu/Debian Notes:

  • You must explicitly enable GCC 11 during configuration.
  • Qt WebEngine is not enabled by default and must be turned on manually.
  • If you want to use system SDL2 instead of Yuzu’s bundled version, you must disable it explicitly.

Fedora

Supported:

  • Fedora 32+
  • Fedora 36+ requires Clang due to GCC 12 compatibility issues.

Install dependencies:

sudo dnf install \
autoconf ccache cmake fmt-devel gcc gcc-c++ \
glslang hidapi-devel json-devel libtool \
libusb1-devel libzstd-devel lz4-devel nasm \
ninja-build openssl-devel pulseaudio-libs-devel \
qt5-linguist qt5-qtbase-devel qt5-qtbase-private-devel \
qt5-qtwebengine-devel qt5-qtmultimedia-devel \
speexdsp-devel wayland-devel zlib-devel \
ffmpeg-devel libXext-devel

Extra Notes:

  1. Enable RPM Fusion (free) to access ffmpeg-devel
  2. Fedora 36+ users should configure CMake to use Clang

Building Yuzu

Before building, make sure submodules are initialized:

git submodule update --init --recursive

Release Build (Recommended)

Optimized for performance and daily use.

mkdir build && cd build
cmake .. -GNinja \
-DYUZU_USE_BUNDLED_VCPKG=ON \
-DYUZU_TESTS=OFF
ninja
sudo ninja install

Debug Build (Slow, For Development)

Useful when stepping through code or tracking crashes.

mkdir build && cd build
cmake .. -GNinja \
-DCMAKE_BUILD_TYPE=Debug \
-DYUZU_USE_BUNDLED_VCPKG=ON \
-DYUZU_TESTS=OFF
ninja

Release With Debug Symbols

Best balance between performance and debuggability.

mkdir build && cd build
cmake .. -GNinja \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DYUZU_USE_BUNDLED_VCPKG=ON \
-DYUZU_TESTS=OFF
ninja

Running Without Installing

Compiled binaries are located here:

build/bin/
  • CLI version:
./yuzu-cmd
  • Qt GUI:
./yuzu

Debugging Yuzu on Linux

If you want crash reports that are actually useful:

  • Turn on CPU Debugging in Yuzu.
  • Make sure both Host MMU emulation options are off.

Then start Yuzu under GDB:

cd data
gdb ../build/bin/yuzu

Inside GDB:

run
bt

This provides a full backtrace showing where and why a crash occurred.