Skip to main content
Dolphin uses CMake for building on Linux. This guide covers all three build types: global installation, local development, and portable builds.

​
Prerequisites

​
Required Software

  • CMake: Version 3.20 or later
  • Git: For cloning the repository
  • GCC: Version 12 or later, OR Clang: Version 15 or later
  • Make or Ninja: Build system backend

​
Compiler Requirements

Dolphin requires a modern compiler with C++23 support:
  • GCC 12+: Recommended for most distributions
  • Clang 15+: Alternative compiler
CMake will inform you if your compiler is too old.

​
Dependencies

Dolphin bundles many dependencies in Externals/. CMake will inform you if any additional system packages are needed. For optimal builds, consider installing system development libraries. Refer to the Dolphin wiki for distribution-specific package lists.

​
Build Type Overview

Linux supports three distinct build types:
Build TypeUse CaseRoot RequiredPortable
GlobalSystem-wide installationYes (for install)No
LocalDevelopment and testingNoNo
PortableMultiple setups, external storageNoYes

​
Global Build (System Installation)

This build type installs Dolphin system-wide, making it available to all users.
1
Clone and Initialize
2
git clone https://github.com/dolphin-emu/dolphin.git
cd dolphin
git submodule update --init --recursive
3
Create Build Directory
4
mkdir build
cd build
5
Configure with CMake
6
cmake ..
7
CMake will check for dependencies and inform you of any missing packages or if bundled versions will be used.
8
Build
9
make -j $(nproc)
10
The -j $(nproc) flag uses all available CPU cores for parallel compilation.
11
Install
12
sudo make install
13
This installs Dolphin to the standard system directories (typically /usr/local/).

​
Uninstalling Global Builds

To uninstall a global build: 
cd build
cat install_manifest.txt | xargs -d '\n' rm
This must be run as root from the original build directory.

​
Local Build (Development)

Local builds are ideal for development as they don’t require root access and create relocatable binaries.
1
Clone and Initialize
2
git clone https://github.com/dolphin-emu/dolphin.git
cd dolphin
git submodule update --init --recursive
3
Create Build Directory
4
mkdir Build
cd Build
5
Configure with Local Dev Option
6
cmake .. -DLINUX_LOCAL_DEV=true
7
The LINUX_LOCAL_DEV option enables relocatable binary creation.
8
Build
9
make -j $(nproc)
11
ln -s ../../Data/Sys Binaries/
12
This creates a symbolic link to the Sys folder needed by Dolphin.

​
Running Local Builds

Run Dolphin from the build directory: 
./Binaries/dolphin-emu

​
Portable Build

Portable builds can be stored on external storage and used across different Linux systems. They’re also useful for maintaining multiple Dolphin configurations for testing, development, or TAS work.
1
Clone and Initialize
2
git clone https://github.com/dolphin-emu/dolphin.git
cd dolphin
git submodule update --init --recursive
3
Create Build Directory
4
mkdir Build
cd Build
5
Configure with Local Dev Option
6
cmake .. -DLINUX_LOCAL_DEV=true
7
Build
8
make -j $(nproc)
9
Copy Sys Files
10
cp -r ../Data/Sys/ Binaries/
11
Unlike local builds, portable builds copy (not symlink) the Sys folder.
12
Create Portable Flag
13
touch Binaries/portable.txt
14
The presence of portable.txt tells Dolphin to store user data locally.

​
Using Portable Builds

Portable builds store all user data (saves, configs, etc.) in the Binaries/ directory alongside the executable. You can:
  • Copy the entire Binaries/ folder to external storage
  • Run on different Linux systems
  • Maintain multiple independent Dolphin setups

​
CMake Build Options

Customize your build with CMake options:

​
Common Options

# Release build (optimized)
cmake .. -DCMAKE_BUILD_TYPE=Release

# Debug build (with debug symbols)
cmake .. -DCMAKE_BUILD_TYPE=Debug

# Release with debug info
cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo

​
Combining Options

Multiple options can be combined: 
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DLINUX_LOCAL_DEV=true \
  -DENABLE_LTO=ON \
  -DUSE_SYSTEM_LIBS=AUTO

​
Using Ninja Instead of Make

Ninja is faster than Make for incremental builds: 
# Configure with Ninja
cmake .. -GNinja

# Build with Ninja
ninja

# Use all cores (Ninja does this by default)
ninja -j $(nproc)

​
Advanced Build Scenarios

​
Generic Build (No JIT)

For unsupported architectures or when JIT is not desired: 
cmake .. -DENABLE_GENERIC=ON
Generic builds are significantly slower as they disable the JIT compiler.

​
Cross-Compilation

For cross-compiling to different architectures, use CMake toolchain files: 
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/toolchain.cmake

​
Custom Install Prefix

Change the installation directory: 
cmake .. -DCMAKE_INSTALL_PREFIX=/opt/dolphin
sudo make install

​
Troubleshooting

​
Compiler Too Old

Error: CMake reports compiler version is too old Solution: Install a newer compiler: 
# Ubuntu/Debian - Install GCC 12
sudo apt install gcc-12 g++-12

# Use the newer compiler
cmake .. -DCMAKE_C_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12

​
Missing Dependencies

Error: CMake reports missing packages Solution: CMake will inform you which packages are missing. Install them using your distribution’s package manager, or let CMake use bundled versions.

​
Submodules Not Initialized

Error: Missing files from Externals directory Solution: 
git submodule update --init --recursive

​
Build Errors After Git Pull

Solution: Clean and rebuild: 
cd build
rm -rf *
cmake ..
make -j $(nproc)

​
Sys Folder Not Found

Error: Dolphin can’t find the Sys folder Solution:
  • Local builds: Ensure the symlink exists: ln -s ../../Data/Sys Binaries/
  • Portable builds: Ensure Sys was copied: cp -r ../Data/Sys/ Binaries/

​
Distribution-Specific Notes

​
Ubuntu/Debian

# Install build dependencies
sudo apt install cmake git g++ libgl1-mesa-dev libx11-dev \
  libxrandr-dev libudev-dev libevdev-dev libsfml-dev \
  libminiupnpc-dev libmbedtls-dev libcurl4-openssl-dev \
  libhidapi-dev libbluetooth-dev

​
Fedora

# Install build dependencies
sudo dnf install cmake git gcc-c++ mesa-libGL-devel \
  libX11-devel libXrandr-devel systemd-devel libevdev-devel \
  SFML-devel miniupnpc-devel mbedtls-devel libcurl-devel \
  hidapi-devel bluez-libs-devel

​
Arch Linux

# Install build dependencies
sudo pacman -S cmake git gcc mesa libx11 libxrandr \
  systemd libevdev sfml miniupnpc mbedtls curl hidapi bluez-libs
These are example package lists. CMake will inform you of any missing dependencies specific to your configuration.

​
Next Steps

After building:
  • Global builds: Run dolphin-emu from anywhere
  • Local/Portable builds: Run ./Binaries/dolphin-emu from the build directory
  • User data is stored in ~/.local/share/dolphin-emu/ (or Binaries/User/ for portable builds)