Building from Source

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

Download and install MSYS2
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

export TOOLCHAIN="ucrt-x86_64"

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
MacPorts

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)

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

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.

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

Remote Build (GitHub Actions)

You can build Sunshine remotely using GitHub Actions:

Fork the Sunshine repository
Go to the Actions tab in your fork
Enable workflows if prompted
Manually trigger the CI workflow
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

Clean build directory:
```
rm -rf build
mkdir build
```
Check compiler version:
```
gcc --version  # or clang --version
```

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

Contributing

​Prerequisites

​Compiler Requirements

​Common Tools

​Clone the Repository

​Platform-Specific Dependencies

​Debian/Ubuntu

​Fedora

​Arch Linux

​Optional: CUDA Toolkit (for NVFBC capture)

​KMS Capture Permissions

​Install MSYS2

​Update MSYS2

​Set Toolchain Variable

​Install Dependencies

​Optional: .NET SDK (for WiX installer)

​Install Homebrew

​Install Dependencies

​Optional: Install Documentation Tools

​Fix OpenSSL Headers (if needed)

​Install MacPorts

​Install Dependencies

​Optional: Install Documentation Tools

​Install Dependencies

​Build Instructions

​Basic Build

​Build with Custom Options

​CMake Build Options

​Common Options

​Linux-Specific Options

​Publisher Options

​Creating Packages

​Remote Build (GitHub Actions)

​Build Troubleshooting

​CMake Version Issues

​Submodule Issues

​Build Failures

​Node.js/npm Issues

​Next Steps

Architecture

Contributing

Build docs developers (and LLMs) love

Prerequisites

Compiler Requirements

Common Tools

Clone the Repository

Platform-Specific Dependencies

Debian/Ubuntu

Fedora

Arch Linux

Optional: CUDA Toolkit (for NVFBC capture)

KMS Capture Permissions

Install MSYS2

Update MSYS2

Set Toolchain Variable

Install Dependencies

Optional: .NET SDK (for WiX installer)

Install Homebrew

Install Dependencies

Optional: Install Documentation Tools

Fix OpenSSL Headers (if needed)

Install MacPorts

Install Dependencies

Optional: Install Documentation Tools

Install Dependencies

Build Instructions

Basic Build

Build with Custom Options

CMake Build Options

Common Options

Linux-Specific Options

Publisher Options

Creating Packages

Remote Build (GitHub Actions)

Build Troubleshooting

CMake Version Issues

Submodule Issues

Build Failures

Node.js/npm Issues

Next Steps