Setup#
The recommended method for running Sunshine is to use the binaries bundled with the latest release.
Binaries#
Binaries of Sunshine are created for each release. They are available for Linux, macOS, and Windows. Binaries can be found in the latest release.
Tip
Some third party packages also exist. See Third Party Packages. No support will be provided for third party packages!
Install#
Warning
The Docker images are not recommended for most users. No support will be provided!
Docker images are available on Dockerhub.io and ghcr.io.
See Docker for additional information.
CUDA Compatibility
CUDA is used for NVFBC capture.
Tip
See CUDA GPUS to cross reference Compute Capability to your GPU.
Package |
CUDA Version |
Min Driver |
CUDA Compute Capabilities |
---|---|---|---|
PKGBUILD |
User dependent |
User dependent |
User dependent |
sunshine.AppImage |
11.8.0 |
450.80.02 |
35;50;52;60;61;62;70;75;80;86;90 |
sunshine.pkg.tar.zst |
11.8.0 |
450.80.02 |
35;50;52;60;61;62;70;75;80;86;90 |
sunshine_{arch}.flatpak |
12.0.0 |
525.60.13 |
50;52;60;61;62;70;75;80;86;90 |
sunshine-debian-bookworm-{arch}.deb |
12.0.0 |
525.60.13 |
50;52;60;61;62;70;75;80;86;90 |
sunshine-debian-bullseye-{arch}.deb |
11.8.0 |
450.80.02 |
35;50;52;60;61;62;70;75;80;86;90 |
sunshine-fedora-38-{arch}.rpm |
unavailable |
unavailable |
none |
sunshine-fedora-39-{arch}.rpm |
unavailable |
unavailable |
none |
sunshine-ubuntu-20.04-{arch}.deb |
11.8.0 |
450.80.02 |
35;50;52;60;61;62;70;75;80;86;90 |
sunshine-ubuntu-22.04-{arch}.deb |
11.8.0 |
450.80.02 |
35;50;52;60;61;62;70;75;80;86;90 |
According to AppImageLint the supported distro matrix of the AppImage is below.
✔ Debian bullseye
✔ Debian bookworm
✔ Debian trixie
✖ Debian sid
✔ Ubuntu mantic
✔ Ubuntu lunar
✔ Ubuntu jammy
✔ Ubuntu focal
✖ Ubuntu bionic
✖ Ubuntu xenial
✖ Ubuntu trusty
✖ CentOS 7
Download
sunshine.AppImage
to your home directory.cd ~ wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.AppImage
Open terminal and run the following code.
./sunshine.AppImage --install
- Start:
./sunshine.AppImage --install && ./sunshine.AppImage
- Uninstall:
./sunshine.AppImage --remove
Open terminal and run the following code.
wget https://github.com/LizardByte/Sunshine/releases/latest/download/PKGBUILD makepkg -fi
- Uninstall:
pacman -R sunshine
Open terminal and run the following code.
wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.pkg.tar.zst pacman -U --noconfirm sunshine.pkg.tar.zst
- Uninstall:
pacman -R sunshine
Download
sunshine-{distro}-{distro-version}-{arch}.deb
and run the following code.sudo apt install -f ./sunshine-{distro}-{distro-version}-{arch}.deb
Note
The
{distro-version}
is the version of the distro we built the package on. The{arch}
is the architecture of your operating system.Tip
You can double click the deb file to see details about the package and begin installation.
- Uninstall:
sudo apt remove sunshine
Important
The instructions provided here are for the version supplied in the latest release, which does not necessarily match the version in the Flathub repository!
Install Flatpak as required.
Download
sunshine_{arch}.flatpak
and run the following code.Note
Be sure to replace
{arch}
with the architecture for your operating system.- System level (recommended)
flatpak install --system ./sunshine_{arch}.flatpak
- User level
flatpak install --user ./sunshine_{arch}.flatpak
- Additional installation (required)
flatpak run --command=additional-install.sh dev.lizardbyte.sunshine
- Start:
- X11 and NVFBC capture (X11 Only)
flatpak run dev.lizardbyte.sunshine
- KMS capture (Wayland & X11)
sudo -i PULSE_SERVER=unix:$(pactl info | awk '/Server String/{print$3}') \ flatpak run dev.lizardbyte.sunshine
- Uninstall:
flatpak run --command=remove-additional-install.sh dev.lizardbyte.sunshine flatpak uninstall --delete-data dev.lizardbyte.sunshine
Add rpmfusion repositories by running the following code.
sudo dnf install \ https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \ https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
Download
sunshine-{distro}-{distro-version}-{arch}.rpm
and run the following code.sudo dnf install ./sunshine-{distro}-{distro-version}-{arch}.rpm
Note
The
{distro-version}
is the version of the distro we built the package on. The{arch}
is the architecture of your operating system.Tip
You can double click the rpm file to see details about the package and begin installation.
- Uninstall:
sudo dnf remove sunshine
The deb, rpm, Flatpak and AppImage packages should handle these steps automatically. Third party packages may not.
Sunshine needs access to uinput to create mouse and gamepad events.
- Create udev rules.
echo 'KERNEL=="uinput", SUBSYSTEM=="misc", OPTIONS+="static_node=uinput", TAG+="uaccess"' | \ sudo tee /etc/udev/rules.d/85-sunshine.rules
Optionally, configure autostart service
filename:
~/.config/systemd/user/sunshine.service
- contents:
[Unit] Description=Sunshine self-hosted game stream host for Moonlight. StartLimitIntervalSec=500 StartLimitBurst=5 [Service] ExecStart=<see table> Restart=on-failure RestartSec=5s #Flatpak Only #ExecStop=flatpak kill dev.lizardbyte.sunshine [Install] WantedBy=graphical-session.target
package
ExecStart
Auto Configured
aur
/usr/bin/sunshine
✔
deb
/usr/bin/sunshine
✔
rpm
/usr/bin/sunshine
✔
AppImage
~/sunshine.AppImage
✔
Flatpak
flatpak run dev.lizardbyte.sunshine
✔
- Start once
systemctl --user start sunshine
- Start on boot
systemctl --user enable sunshine
- Additional Setup for KMS
Note
cap_sys_admin
may as well be root, except you don’t need to be root to run it. It is necessary to allow Sunshine to use KMS.- Enable
sudo setcap cap_sys_admin+p $(readlink -f $(which sunshine))
- Disable (for Xorg/X11)
sudo setcap -r $(readlink -f $(which sunshine))
- Reboot
sudo reboot now
Important
Sunshine on macOS is experimental. Gamepads do not work. Other features may not work as expected.
Warning
The dmg does not include runtime dependencies. This package is not recommended for most users. No support will be provided!
Download the
sunshine.dmg
file and install it.
- Uninstall:
cd /etc/sunshine/assets uninstall_pkg.sh
Install MacPorts
Update the Macports sources.
sudo nano /opt/local/etc/macports/sources.conf
- Add this line, replacing your username, below the line that starts with
rsync
. file:///Users/<username>/ports
Ctrl+x
, thenY
to exit and save changes.- Add this line, replacing your username, below the line that starts with
Download and install by running the following code.
mkdir -p ~/ports/multimedia/sunshine cd ~/ports/multimedia/sunshine curl -O https://github.com/LizardByte/Sunshine/releases/latest/download/Portfile cd ~/ports portindex sudo port install sunshine
The first time you start Sunshine, you will be asked to grant access to screen recording and your microphone.
Optionally, install service
sudo port load Sunshine
- Uninstall:
sudo port uninstall sunshine
Sunshine can only access microphones on macOS due to system limitations. To stream system audio use Soundflower or BlackHole.
Note
Command Keys are not forwarded by Moonlight. Right Option-Key is mapped to CMD-Key.
Caution
Gamepads are not currently supported.
Download and install
sunshine-windows-installer.exe
Attention
You should carefully select or unselect the options you want to install. Do not blindly install or enable features.
To uninstall, find Sunshine in the list here and select “Uninstall” from the overflow menu. Different versions of Windows may provide slightly different steps for uninstall.
Warning
By using this package instead of the installer, performance will be reduced. This package is not recommended for most users. No support will be provided!
Download and extract
sunshine-windows-portable.zip
Open command prompt as administrator
Firewall rules
- Install:
cd /d {path to extracted directory} scripts/add-firewall-rule.bat
- Uninstall:
cd /d {path to extracted directory} scripts/delete-firewall-rule.bat
Virtual Gamepad Support
- Install:
cd /d {path to extracted directory} scripts/install-gamepad.bat
- Uninstall:
cd /d {path to extracted directory} scripts/uninstall-gamepad.bat
Windows service
- Install:
cd /d {path to extracted directory} scripts/install-service.bat scripts/autostart-service.bat
- Uninstall:
cd /d {path to extracted directory} scripts/uninstall-service.bat
To uninstall, delete the extracted directory which contains the sunshine.exe
file.
Usage#
If Sunshine is not installed/running as a service, then start sunshine with the following command, unless a start command is listed in the specified package install instructions above.
Note
A service is a process that runs in the background. This is the default when installing Sunshine from the Windows installer. Running multiple instances of Sunshine is not advised.
- Basic usage
sunshine
- Specify config file
sunshine <directory of conf file>/sunshine.conf
Note
You do not need to specify a config file. If no config file is entered the default location will be used.
Attention
The configuration file specified will be created if it doesn’t exist.
- Start Sunshine over SSH (Linux/X11)
Assuming you are already logged into the host, you can use this command
ssh <user>@<ip_address> 'export DISPLAY=:0; sunshine'
If you are logged into the host with only a tty (teletypewriter), you can use
startx
to start the X server prior to executing sunshine. You nay need to addsleep
betweenstartx
andsunshine
to allow more time for the display to be ready.ssh <user>@<ip_address> 'startx &; export DISPLAY=:0; sunshine'
Tip
You could also utilize the
~/.bash_profile
or~/.bashrc
files to setup theDISPLAY
variable.See also
See Remote SSH Headless Setup on how to setup a headless streaming server without autologin and dummy plugs (X11 + NVidia GPUs)
Configure Sunshine in the web ui
The web ui is available on https://localhost:47990 by default. You may replace localhost with your internal ip address.
Attention
Ignore any warning given by your browser about “insecure website”. This is due to the SSL certificate being self signed.
Caution
If running for the first time, make sure to note the username and password that you created.
Add games and applications.
Adjust any configuration settings as needed.
In Moonlight, you may need to add the PC manually.
When Moonlight requests for you insert the pin:
Login to the web ui
Go to “PIN” in the Navbar
Type in your PIN and press Enter, you should get a Success Message
In Moonlight, select one of the Applications listed
Network#
The Sunshine user interface will be available on port 47990 by default.
Warning
Exposing ports to the internet can be dangerous. Do this at your own risk.
Arguments#
To get a list of available arguments run the following:
sunshine --help
./sunshine.AppImage --help
flatpak run --command=sunshine dev.lizardbyte.Sunshine --help
Shortcuts#
All shortcuts start with CTRL + ALT + SHIFT
, just like Moonlight
CTRL + ALT + SHIFT + N
- Hide/Unhide the cursor (This may be useful for Remote Desktop Mode for Moonlight)CTRL + ALT + SHIFT + F1/F12
- Switch to different monitor for Streaming
Application List#
Applications should be configured via the web UI.
A basic understanding of working directories and commands is required.
You can use Environment variables in place of values
$(HOME)
will be replaced by the value of$HOME
$$
will be replaced by$
, e.g.$$(HOME)
will be become$(HOME)
env
- Adds or overwrites Environment variables for the commands/applications run by Sunshine"Variable name":"Variable value"
apps
- The list of applicationsAdvanced users may want to edit the application list manually. The format is
json
.- Example
json
application: { "cmd": "command to open app", "detached": [ "some-command", "another-command" ], "image-path": "/full-path/to/png-image", "name": "An App", "output": "/full-path/to/command-log-file", "prep-cmd": [ { "do": "some-command", "undo": "undo-that-command" } ], "working-dir": "/full-path/to/working-directory" }
cmd
- The main applicationdetached
- A list of commands to be run and forgotten aboutIf not specified, a process is started that sleeps indefinitely
image-path
- The full path to the cover art image to use.name
- The name of the application/gameoutput
- The file where the output of the command is storedauto-detach
- Specifies whether the app should be treated as detached if it exits quicklywait-all
- Specifies whether to wait for all processes to terminate rather than just the initial processexit-timeout
- Specifies how long to wait in seconds for the process to gracefully exit (default: 5 seconds)prep-cmd
- A list of commands to be run before/after the applicationIf any of the prep-commands fail, starting the application is aborted
do
- Run before the applicationIf it fails, all
undo
commands of the previously succeededdo
commands are run
undo
- Run after the application has terminatedFailures of
undo
commands are ignored
working-dir
- The working directory to use. If not specified, Sunshine will use the application directory.
- Example
For more examples see app examples.
Considerations#
On Windows, Sunshine uses the Desktop Duplication API which only supports capturing from the GPU used for display. If you want to capture and encode on the eGPU, connect a display or HDMI dummy display dongle to it and run the games on that display.
When an application is started, if there is an application already running, it will be terminated.
When the application has been shutdown, the stream shuts down as well.
For example, if you attempt to run
steam
as acmd
instead ofdetached
the stream will immediately fail. This is due to the method in which the steam process is executed. Other applications may behave similarly.This does not apply to
detached
applications.
The “Desktop” app works the same as any other application except it has no commands. It does not start an application, instead it simply starts a stream. If you removed it and would like to get it back, just add a new application with the name “Desktop” and “desktop.png” as the image path.
For the Linux flatpak you must prepend commands with
flatpak-spawn --host
.
HDR Support#
Streaming HDR content is officially supported on Windows hosts and experimentally supported for Linux hosts.
General HDR support information and requirements:
HDR must be activated in the host OS, which may require an HDR-capable display or EDID emulator dongle connected to your host PC.
You must also enable the HDR option in your Moonlight client settings, otherwise the stream will be SDR (and probably overexposed if your host is HDR).
A good HDR experience relies on proper HDR display calibration both in the OS and in game. HDR calibration can differ significantly between client and host displays.
You may also need to tune the brightness slider or HDR calibration options in game to the different HDR brightness capabilities of your client’s display.
Some GPUs video encoders can produce lower image quality or encoding performance when streaming in HDR compared to SDR.
Additional information:
HDR streaming is supported for Intel, AMD, and NVIDIA GPUs that support encoding HEVC Main 10 or AV1 10-bit profiles.
We recommend calibrating the display by streaming the Windows HDR Calibration app to your client device and saving an HDR calibration profile to use while streaming.
Older games that use NVIDIA-specific NVAPI HDR rather than native Windows HDR support may not display properly in HDR.
HDR streaming is supported for Intel and AMD GPUs that support encoding HEVC Main 10 or AV1 10-bit profiles using VAAPI.
The KMS capture backend is required for HDR capture. Other capture methods, like NvFBC or X11, do not support HDR.
You will need a desktop environment with a compositor that supports HDR rendering, such as Gamescope or KDE Plasma 6.
Tutorials and Guides#
Tutorial videos are available here.
Guides are available here.
Community!
Tutorials and Guides are community generated. Want to contribute? Reach out to us on our discord server.