Last tested: Raspberry Pi OS Bookworm 64-bit | April 11, 2026 | Raspberry Pi 4 Model B and Raspberry Pi 5
Sunshine and Moonlight on Raspberry Pi turns the board into a game streaming client for a PC sitting elsewhere in the house. Sunshine runs on the Windows PC as the host server, encoding your screen and game library. Moonlight runs on the Pi as the client, decoding the stream and passing controller input back. The result is low-latency local game streaming to any display the Pi is connected to, with optional remote play over a VPN when you are away from home.
Both Pi 4 and Pi 5 support Moonlight Qt. The Pi 5 handles higher bitrates and HEVC decoding more reliably. This guide covers setup from first boot through pairing, streaming, troubleshooting, and remote access.
Key Takeaways
- Sunshine runs on the PC and hosts your game library. Moonlight runs on the Pi and receives the stream. They communicate over your local network.
- Sunshine does not require GeForce Experience and supports NVIDIA, AMD, and Intel GPUs.
- Ethernet gives the best results. 5GHz Wi-Fi works at moderate bitrates but adds variable latency.
- Pi 5 handles 1080p60 and HEVC more reliably than Pi 4. Pi 4 works well at 1080p with H.264.
- On Raspberry Pi OS Bookworm, audio is handled by PipeWire with a PulseAudio compatibility layer. The setup is slightly different from older guides.
- For remote play outside your LAN, use ZeroTier or Tailscale rather than exposing Sunshine ports directly to the internet.
What You Need
Pi hardware
- Raspberry Pi 4 (2GB minimum, 4GB recommended) or Raspberry Pi 5
- 32GB+ microSD card or USB SSD for OS
- Official power supply (5V/3A for Pi 4, 5V/5A for Pi 5)
- HDMI or microHDMI cable to a display
- USB or Bluetooth game controller
- Ethernet cable (strongly recommended over Wi-Fi)
- Active cooling case. Streaming loads the GPU decoder continuously.
PC host requirements
- Windows 10 or 11 (64-bit)
- GPU with hardware encoding: NVIDIA GTX 600+, AMD RX 400+, or Intel 6th gen+ integrated graphics
- Sunshine server installed (replaces GeForce Experience GameStream)
- Headless HDMI dongle if the PC runs without a monitor
Network requirements
| Connection type | Suitable for | Notes |
|---|---|---|
| Gigabit Ethernet | 1080p and 4K streaming | Best option, lowest latency |
| 5GHz Wi-Fi | 1080p at moderate bitrate | Keep Pi close to access point |
| 2.4GHz Wi-Fi | 720p only | High latency, not recommended |
Step 1: Prepare the Raspberry Pi
Flash and update Raspberry Pi OS
Flash Raspberry Pi OS Bookworm 64-bit using Raspberry Pi Imager. Configure hostname, SSH, and Wi-Fi credentials in the Imager settings before writing the image. After first boot, update fully:
sudo apt update && sudo apt full-upgrade -y
sudo rebootGPU memory on Pi 4
On Raspberry Pi 4, increasing GPU memory helps with video decoding. Add to /boot/firmware/config.txt (the Bookworm path, not the older /boot/config.txt):
echo "gpu_mem=128" | sudo tee -a /boot/firmware/config.txt
sudo rebootOn Raspberry Pi 5, the GPU memory allocation works differently and this setting has less direct impact. Leave it at the default on Pi 5 unless you experience decoding issues.
Audio on Raspberry Pi OS Bookworm
Raspberry Pi OS Bookworm uses PipeWire as the default audio system, with a PulseAudio compatibility layer. Moonlight works with this setup, but the commands differ from older guides that reference PulseAudio directly. Confirm audio is working:
# Check PipeWire status
systemctl --user status pipewire
# Test audio output
paplay /usr/share/sounds/alsa/Front_Center.wavIf the test sound plays through your display’s speakers, audio is configured correctly. If not, open the sound settings in Raspberry Pi OS and confirm HDMI is selected as the output device.
Connect display and controller
Connect the Pi to a display via HDMI and set the resolution to 1080p in display settings. Connect a USB controller or pair a Bluetooth controller. For a long-running streaming setup, booting from USB SSD rather than microSD removes the most common reliability failure point. See Booting Raspberry Pi from USB SSD and Preventing SD Card Corruption on Raspberry Pi.
Step 2: Install Sunshine and Moonlight on Raspberry Pi
sudo apt install moonlight-qt -yMoonlight Qt installs from the Raspberry Pi OS repository. After installation it appears in the Games or Internet menu, or launch it from the terminal:
moonlight-qtDo not attempt to pair yet. Set up Sunshine on the PC first so the Pi has something to connect to.
Step 3: Set Up Sunshine on the PC
Download and install Sunshine
Download the latest Sunshine release from the official GitHub page. Run the installer and follow the prompts. Sunshine installs as a background service and starts automatically. It does not require GeForce Experience.
Access the Sunshine web interface
Open a browser on the PC and navigate to:
https://localhost:47990Create your username and password on first access. The web interface is where you manage applications, configure bitrate and resolution, and monitor active streams.
Add applications
In the Sunshine web interface, go to Apps and add the applications you want to stream. For each app, provide a name, the path to the executable, and the working directory. Add Steam as a single entry and use Big Picture mode for a controller-friendly interface. Add desktop mode as a separate entry if you want full Windows desktop access from the Pi.
Allow Sunshine through Windows Firewall
Sunshine needs inbound access on several ports for LAN streaming. The installer usually handles this, but if pairing fails, check that Windows Firewall has rules allowing Sunshine. Enable Run on Startup in the Sunshine settings so it is always available without manual intervention.
Step 4: Pair Moonlight with Sunshine
Find the local IP address of the PC running Sunshine. On Windows, open a command prompt and run ipconfig. On the Raspberry Pi, open Moonlight and select Add Host. Enter the PC’s IP address. Moonlight sends a pairing request and displays a 4-digit PIN on screen. Enter that PIN in the Sunshine web interface under the pairing notification that appears. Once paired, the app list from Sunshine appears in Moonlight automatically.
If no apps appear after pairing, restart both Moonlight and Sunshine and confirm Sunshine is running in the system tray.
Step 5: Start Streaming
Choose stream settings
Before launching an app, configure stream quality in Moonlight settings. Start conservatively and raise settings once you confirm the stream is stable:
- Resolution: 1080p for most setups. 720p on weaker networks or Pi 4 with Wi-Fi.
- Frame rate: 60fps for smooth gameplay, 30fps if the network or Pi struggles
- Bitrate: Start at 15 Mbps. Raise toward 20 to 30 Mbps on wired Ethernet if the stream looks soft or compressed.
- Codec: H.264 is the most compatible. HEVC gives better quality at lower bitrates but requires more decode overhead.
Launch a game
Select an app from the Moonlight list and click to start. The stream launches fullscreen. If the screen stays black, verify the Sunshine session is active and the selected resolution is supported by the connected display. Some games need to be run once on the PC first to accept licence agreements before Sunshine can launch them remotely.
Exit the stream
Ctrl + Alt + Shift + QThis returns you to the Moonlight menu without closing the game on the PC. Remap this shortcut in Moonlight settings if the default conflicts with a game binding.
Remote Streaming Outside Your LAN
Use a mesh VPN instead of port forwarding
Exposing Sunshine directly to the internet via port forwarding creates an unnecessary attack surface. The safer approach is a mesh VPN that makes your Pi and PC appear to be on the same virtual network regardless of physical location. ZeroTier and Tailscale are both reliable free options:
- Tailscale is the simpler setup. Install on both devices, sign in, and they appear on the same network immediately. Uses WireGuard under the hood.
- ZeroTier requires creating a network on the ZeroTier website and approving each device, but gives more control over the network configuration.
Once the VPN is running, Moonlight connects to the PC’s VPN IP address the same way it would on a local network. No port forwarding required.
Port forwarding if you must
If you cannot use a VPN, forward these ports on your router to the PC’s local IP:
- TCP 47984, 47989, 47990
- UDP 47998, 47999, 48000, 48010
Assign the PC a static local IP or DHCP reservation so the forwarding rules stay valid. For remote streaming, keep bitrate expectations realistic: 1080p at 30fps is achievable on most home connections with 10+ Mbps upload. Use 720p if latency is high.
Pi 4 vs Pi 5 for Streaming
| Feature | Raspberry Pi 4 | Raspberry Pi 5 |
|---|---|---|
| 1080p 60fps H.264 | Good | Excellent |
| 1080p 60fps HEVC | Marginal at high bitrate | Good |
| 4K streaming | Not recommended | Works on Ethernet |
| Thermal throttling | Common without fan | Less frequent with fan |
| Desktop streaming | Usable | Smooth |
| Recommended codec | H.264 | H.264 or HEVC |
For most setups, Pi 4 at 1080p H.264 over Ethernet delivers a good experience. Pi 5 is worth it if you want HEVC quality gains, higher bitrates, or smoother desktop streaming. Both benefit significantly from active cooling. A fanless Pi 4 throttles after a few minutes of sustained 1080p60 decoding. See Steam Link on Raspberry Pi 5 for a detailed look at Pi 5 streaming performance and codec comparison, since the same hardware considerations apply here.
Troubleshooting
Black screen after connecting
Confirm the display supports the selected resolution. Use 1080p rather than 4K on Pi 4. Verify Sunshine is running on the PC and the selected app path is correct. If the PC has no monitor connected, a headless HDMI dongle is required. Otherwise Sunshine cannot capture a display.
No audio
# Check PipeWire status on Bookworm
systemctl --user status pipewire
# Confirm audio output device
pactl info | grep "Default Sink"
# Test playback
paplay /usr/share/sounds/alsa/Front_Center.wavIf the default sink is not the HDMI output, change it in the Raspberry Pi OS sound settings. On Bookworm, do not attempt to install or restart PulseAudio directly. Use PipeWire commands instead.
Controller not responding
# Add user to input group if controller is not detected
sudo usermod -a -G input $USER
# Confirm controller appears in input devices
ls /dev/input/Log out and back in after the group change for it to take effect. USB controllers are more reliable than Bluetooth for streaming. Some Bluetooth controllers introduce input lag that is particularly noticeable in fast-paced games.
High latency or stutter
- Switch from Wi-Fi to Ethernet if possible
- Lower bitrate in Moonlight settings
- Confirm Sunshine is using hardware encoding. Check the Sunshine web interface under diagnostics
- Check CPU and GPU load on the PC. If the encoder is saturated, frame times become irregular
- Check Pi temperature with
vcgencmd measure_temp. Throttling causes decode stutter.
App not launching from Sunshine
Verify the executable path in the Sunshine web interface is correct and points to the actual .exe file. Run the game once locally on the PC to accept any first-run prompts or licence agreements that would block a remote launch. If individual games fail, use desktop mode in Sunshine and launch the game manually from the streamed Windows desktop.
FAQ
Can I use Raspberry Pi Zero or Pi 3?
No. These models lack the GPU pipeline and memory bandwidth for smooth video decoding at streaming resolutions. Pi 4 is the minimum for a usable experience.
Does Sunshine work with AMD or Intel GPUs?
Yes. Sunshine supports NVIDIA NVENC, AMD AMF, and Intel Quick Sync for hardware encoding. GeForce Experience GameStream is NVIDIA-only, but Sunshine is not. This is one of the main reasons to use Sunshine over the older GameStream approach.
Do I need a monitor connected to the PC?
Not if you use a headless HDMI dongle. Without one, Sunshine may fail to capture a display and games will not launch correctly. The dongle tricks the GPU into thinking a monitor is connected and enables a virtual display at the configured resolution.
Can Sunshine run on Linux?
Yes. Sunshine has Linux support but some features, particularly audio capture, may require additional configuration. The setup is less documented than the Windows version. If your gaming PC runs Linux, check the Sunshine GitHub documentation for the current Linux installation steps.
What bitrate should I use for 1080p?
Start at 15 Mbps on Ethernet and raise toward 20 to 30 Mbps if the stream looks soft or compressed. For Wi-Fi, stay at 10 to 15 Mbps and lower if the stream stutters. For remote play, 10 Mbps at 1080p30 is a realistic starting point on most home upload connections.
Is it safe to expose Sunshine to the internet?
Not recommended. Use ZeroTier or Tailscale for remote access instead of opening Sunshine ports on your router. A mesh VPN gives the same result with a much smaller attack surface and no port forwarding required.
Can I stream non-Steam games?
Yes. Add any executable to the Sunshine web interface as a custom app entry. It will appear in Moonlight alongside Steam. Epic Games, GOG, and standalone executables all work the same way.
References
- https://github.com/LizardByte/Sunshine
- https://github.com/moonlight-stream/moonlight-qt
- https://tailscale.com/
- https://www.zerotier.com/
- https://www.raspberrypi.com/software/
About the Author
Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.
Last tested hardware: Raspberry Pi 4 Model B and Raspberry Pi 5. Last tested OS: Raspberry Pi OS Bookworm 64-bit.