Building from Source

Complete guide to building Sunshine from source on all supported platforms

Sunshine uses CMake as its build system and requires CMake version 3.25 or higher. This guide covers building on all supported platforms.

Prerequisites

Compiler Requirements

It is recommended to use one of the following compilers:

Compiler	Version
GCC	13+
Clang	17+
Apple Clang	15+

Common Tools

All platforms require:

• CMake >= 3.25
• Git (for cloning with submodules)
• Ninja or Make (build system)
• Node.js and npm (for Web UI)

Clone the Repository

First, clone the repository with all submodules:

git clone https://github.com/LizardByte/Sunshine.git --recurse-submodules
cd Sunshine
mkdir build

The --recurse-submodules flag is crucial as Sunshine depends on several third-party libraries included as submodules.

Platform-Specific Dependencies

Linux

Debian/Ubuntu

sudo apt-get update
sudo apt-get install -y \
  build-essential \
  cmake \
  ninja-build \
  git \
  libssl-dev \
  libboost-dev \
  libboost-filesystem-dev \
  libboost-locale-dev \
  libboost-log-dev \
  libboost-program-options-dev \
  libboost-thread-dev \
  libavdevice-dev \
  libcurl4-openssl-dev \
  libdrm-dev \
  libevdev-dev \
  libpulse-dev \
  libopus-dev \
  libxtst-dev \
  libx11-dev \
  libxfixes-dev \
  libxrandr-dev \
  libxcb1-dev \
  libxcb-shm0-dev \
  libxcb-xfixes0-dev \
  libwayland-dev \
  wayland-protocols \
  libva-dev \
  libvdpau-dev \
  libminiupnpc-dev \
  libnotify-dev \
  libappindicator3-dev \
  nodejs \
  npm

Fedora

sudo dnf install -y \
  gcc \
  gcc-c++ \
  cmake \
  ninja-build \
  git \
  openssl-devel \
  boost-devel \
  libcurl-devel \
  libdrm-devel \
  libevdev-devel \
  pulseaudio-libs-devel \
  opus-devel \
  libXtst-devel \
  libX11-devel \
  libXfixes-devel \
  libXrandr-devel \
  libxcb-devel \
  wayland-devel \
  wayland-protocols-devel \
  libva-devel \
  libvdpau-devel \
  miniupnpc-devel \
  libnotify-devel \
  libappindicator-gtk3-devel \
  nodejs \
  npm

Arch Linux

sudo pacman -S --needed \
  base-devel \
  cmake \
  ninja \
  git \
  boost \
  openssl \
  opus \
  libevdev \
  libpulse \
  libdrm \
  libx11 \
  libxcb \
  libxfixes \
  libxrandr \
  libxtst \
  wayland \
  wayland-protocols \
  libva \
  libvdpau \
  miniupnpc \
  libnotify \
  libappindicator-gtk3 \
  nodejs \
  npm

Optional: CUDA Toolkit (for NVFBC capture)

Sunshine requires CUDA Toolkit for NVIDIA’s NvFBC (NVIDIA Framebuffer Capture) feature.

The CUDA version you use will determine compatibility with various GPU generations. At the time of writing, CUDA ~12.9 is recommended. See CUDA compatibility for more info.

Install CUDA:

# Download from https://developer.nvidia.com/cuda-toolkit-archive
# Select your distribution and architecture
# Follow NVIDIA's installation instructions

KMS Capture Permissions

If you are using KMS capture, you need to set capabilities on the binary:

sudo cp build/sunshine /tmp
sudo setcap cap_sys_admin+p /tmp/sunshine
sudo getcap /tmp/sunshine
sudo mv /tmp/sunshine build/sunshine

This is required for KMS capture to work. Some post-install scripts handle this automatically.

Windows

Cross-compilation is not supported on Windows. You must build on the target architecture (AMD64 or ARM64).

Install MSYS2

1. Download and install MSYS2
2. Launch the appropriate shell:
   • AMD64: MSYS2 UCRT64
   • ARM64: MSYS2 CLANGARM64

Update MSYS2

pacman -Syu

Close and reopen the shell, then:

pacman -Su

Set Toolchain Variable

UCRT64 (AMD64)

export TOOLCHAIN="ucrt-x86_64"

export TOOLCHAIN="clang-aarch64"

Install Dependencies

pacman -S \
  git \
  mingw-w64-${TOOLCHAIN}-boost \
  mingw-w64-${TOOLCHAIN}-cmake \
  mingw-w64-${TOOLCHAIN}-cppwinrt \
  mingw-w64-${TOOLCHAIN}-curl-winssl \
  mingw-w64-${TOOLCHAIN}-miniupnpc \
  mingw-w64-${TOOLCHAIN}-onevpl \
  mingw-w64-${TOOLCHAIN}-openssl \
  mingw-w64-${TOOLCHAIN}-opus \
  mingw-w64-${TOOLCHAIN}-toolchain

Additional packages for UCRT64:

pacman -S \
  mingw-w64-${TOOLCHAIN}-MinHook \
  mingw-w64-${TOOLCHAIN}-nodejs \
  mingw-w64-${TOOLCHAIN}-nsis

For ARM64: Install Node.js separately for the Web UI.

Optional: .NET SDK (for WiX installer)

To create a WiX installer, install the .NET SDK.

macOS

You can use either Homebrew or MacPorts for dependency management.

Homebrew

Install Homebrew

If not already installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Dependencies

brew install \
  boost \
  cmake \
  miniupnpc \
  ninja \
  node \
  openssl@3 \
  opus \
  pkg-config

Optional: Install Documentation Tools

brew install doxygen graphviz

Fix OpenSSL Headers (if needed)

Intel

ln -s /usr/local/opt/openssl/include/openssl /usr/local/include/openssl

ln -s /opt/homebrew/opt/openssl/include/openssl /opt/homebrew/include/openssl

MacPorts

Install MacPorts

Download and install from macports.org.

Install Dependencies

sudo port install \
  cmake \
  curl \
  libopus \
  miniupnpc \
  ninja \
  npm9 \
  pkgconfig

Optional: Install Documentation Tools

sudo port install doxygen graphviz

FreeBSD

Sunshine support for FreeBSD is experimental and may be incomplete or not work as expected.

Install Dependencies

pkg install -y \
  audio/opus \
  audio/pulseaudio \
  devel/cmake \
  devel/evdev-proto \
  devel/git \
  devel/libayatana-appindicator \
  devel/libevdev \
  devel/libnotify \
  devel/ninja \
  devel/pkgconf \
  ftp/curl \
  graphics/libdrm \
  graphics/wayland \
  multimedia/libva \
  net/miniupnpc \
  ports-mgmt/pkg \
  security/openssl \
  shells/bash \
  www/npm \
  x11/libX11 \
  x11/libxcb \
  x11/libXfixes \
  x11/libXrandr \
  x11/libXtst

Build Instructions

Basic Build

Once dependencies are installed:

cmake -B build -G Ninja -S .
ninja -C build

Build with Custom Options

CMake options can be specified with -D flags:

cmake -B build -G Ninja -S . \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_TESTS=ON \
  -DBUILD_DOCS=OFF \
  -DSUNSHINE_ENABLE_TRAY=ON
ninja -C build

CMake Build Options

Sunshine provides numerous build options in cmake/prep/options.cmake:

Common Options

Option	Default	Description
BUILD_DOCS	ON	Build Doxygen documentation
BUILD_TESTS	ON	Build unit tests
BUILD_WERROR	OFF	Treat compiler warnings as errors
SUNSHINE_ENABLE_TRAY	ON	Enable system tray icon
NPM_OFFLINE	OFF	Use offline npm packages
BOOST_USE_STATIC	ON (OFF on macOS)	Use static Boost libraries

Linux-Specific Options

Option	Default	Description
SUNSHINE_ENABLE_CUDA	ON	Enable CUDA/NVENC support
SUNSHINE_ENABLE_DRM	ON	Enable KMS/DRM capture
SUNSHINE_ENABLE_VAAPI	ON	Enable VAAPI encoding
SUNSHINE_ENABLE_WAYLAND	ON	Enable Wayland capture
SUNSHINE_ENABLE_X11	ON	Enable X11 capture
SUNSHINE_ENABLE_PORTAL	ON	Enable XDG Desktop Portal capture
SUNSHINE_BUILD_APPIMAGE	OFF	Build for AppImage packaging
SUNSHINE_BUILD_FLATPAK	OFF	Build for Flatpak packaging

Publisher Options

For custom builds, you can set publisher metadata:

Option	Description
SUNSHINE_PUBLISHER_NAME	Publisher name
SUNSHINE_PUBLISHER_WEBSITE	Publisher website URL
SUNSHINE_PUBLISHER_ISSUE_URL	Support/issue tracker URL

Example:

cmake -B build -G Ninja -S . \
  -DSUNSHINE_PUBLISHER_NAME="My Company" \
  -DSUNSHINE_PUBLISHER_WEBSITE="https://example.com" \
  -DSUNSHINE_PUBLISHER_ISSUE_URL="https://example.com/support"

Creating Packages

Sunshine uses CPack for package creation.

Linux (DEB)

cpack -G DEB --config ./build/CPackConfig.cmake

cpack -G RPM --config ./build/CPackConfig.cmake

cpack -G FREEBSD --config ./build/CPackConfig.cmake

cpack -G DragNDrop --config ./build/CPackConfig.cmake

cpack -G NSIS --config ./build/CPackConfig.cmake

cpack -G WIX --config ./build/CPackConfig.cmake

cpack -G ZIP --config ./build/CPackConfig.cmake

Remote Build (GitHub Actions)

You can build Sunshine remotely using GitHub Actions:

1. Fork the Sunshine repository
2. Go to the Actions tab in your fork
3. Enable workflows if prompted
4. Manually trigger the CI workflow
5. Download artifacts from the workflow run summary

This is useful for:

• Building on platforms you don’t have access to
• Testing cross-platform compatibility
• Creating release packages

Build Troubleshooting

CMake Version Issues

If your system’s CMake is too old:

# Download a newer CMake binary
wget https://github.com/Kitware/CMake/releases/download/v3.30.1/cmake-3.30.1-linux-x86_64.tar.gz
tar xzf cmake-3.30.1-linux-x86_64.tar.gz
export PATH="$(pwd)/cmake-3.30.1-linux-x86_64/bin:$PATH"

Submodule Issues

If you forgot to clone with --recurse-submodules:

git submodule update --init --recursive

Build Failures

1. Clean build directory:

   rm -rf build
   mkdir build
   

2. Check compiler version:

   gcc --version  # or clang --version
   

3. Verify all dependencies are installed:

   cmake -B build -G Ninja -S . --debug-find
   

Node.js/npm Issues

If Web UI build fails:

# Clear npm cache
npm cache clean --force

# Rebuild Web UI separately
cd src_assets/common/assets/web
npm install
npm run build

Next Steps

Architecture

Learn about Sunshine’s internal architecture

Contributing

Start contributing to the project