Moonlight streaming can turn a spare Raspberry Pi into a free cloud gaming client, and October 2026 gave the idea a fresh boost. Moonlight PC 6.2.0 is the current release and officially supports Raspberry Pi 2, 3, 4 and 5. Pi 4 and Pi 5 support already existed, so the new release mostly rescues older boards that were sitting in drawers.
This tutorial walks you through 13 steps and roughly 45 minutes of work. You will install Sunshine on your gaming PC, put Moonlight on a Raspberry Pi, pair the two, tune the stream, and finish with a launcher script that wakes the PC, checks the network, and starts the game stream every time the Pi boots. The software costs $0 because Moonlight and Sunshine are both free and open source.
One honest caveat before you start. This setup is self-hosted. Your own PC runs the games, and the Pi only decodes video and sends controller input back. If you want to stream from home over Tailscale while traveling, the same Pi client works there too. If you have no gaming PC at all, skip ahead to the section on hosted services, because the free options there changed again this month.
Don't miss new tech stories on Google
Add Tech Insider once in the Google app and our stories appear in your news suggestions.
Why a Raspberry Pi works as a free cloud gaming client
Cloud gaming sounds exotic, but the idea is simple. A powerful machine renders the game, compresses the picture into a video stream, and sends it over the network. A small device on your desk decodes that video and returns your button presses. Commercial services run the powerful machine in a data center. Moonlight and Sunshine let you run it in your own spare room instead.
A Raspberry Pi suits the client role because it never renders a frame of the game. The Pi needs a decent video decoder, a stable network port, and a way to read a controller. It does not need a fast graphics card. That is why a board that cannot run a modern game on its own can still show you a 1080p stream of one.
The project itself has a long history. Moonlight began as a student project at the MHacks hackathon in 2013, built by Case Western Reserve University students, and kept growing at MHacks and HackCWRU in 2014. Today the project’s own documentation describes Moonlight as an open-source client for streaming games from a compatible PC. The documentation also states that Moonlight has no affiliation with NVIDIA.
Hardware longevity matters when you buy a client device. Raspberry Pi’s own product page says the Pi 5 stays in production until at least January 2036. You are not buying into a board that vanishes next spring. Meanwhile the Pi 4 remains an active product too, according to coverage of the October 1 price changes.
Compare that with the other ways to build a game-streaming box. A mini PC costs more. An old laptop draws more power and takes more space. If you are still choosing between streaming clients, our Parsec vs Moonlight vs Steam Link comparison explains where each one wins. For this guide, the Pi wins on price, size, silence, and the fact that you can leave it plugged into a TV forever.
Expect a console-like experience on a wired network. Expect something rougher on weak Wi-Fi. We will measure both in Step 11 so you can decide with numbers instead of guesses.
Prerequisites and versions
Gather these items before you flash anything. The table lists what to have ready and what version to aim for.
| Component | What to use | Notes |
|---|---|---|
| Client board | Raspberry Pi 5 (recommended) or Raspberry Pi 4 | Pi 2 and Pi 3 became officially supported in Moonlight 6.2.0 |
| Client software | Moonlight Qt (Moonlight PC) 6.2.0 or newer | Not listed |
| Host software | Sunshine, latest stable build from the LizardByte/Sunshine releases page | The project ships dated builds often, so grab the newest stable one |
| Client OS | Raspberry Pi OS, current release, 64-bit | Flash it with Raspberry Pi Imager |
| Host PC | Windows 10/11 or a recent Linux distribution with a GPU that has a hardware video encoder | NVENC, AMD and Intel encoders all work with Sunshine |
| Network | Wired Ethernet on both ends, or 5 GHz Wi-Fi on the Pi at minimum | Same router and same subnet for the first pairing |
| Display | HDMI TV or monitor | Pi 4 and Pi 5 use micro-HDMI, so check your cable |
| Controller | Any USB or Bluetooth gamepad | Keyboard and mouse also work |
| Storage and power | microSD card or SSD, plus the official power supply for your Pi model | Weak power supplies cause random crashes |
Raspberry Pi OS 12 or later is the baseline in the Moonlight Qt Raspberry Pi instructions, according to a source checked on October 16, 2026. If a newer release is current when you read this, use it, and read the Moonlight wiki page for Raspberry Pi if anything below disagrees with what you see.
You also need basic comfort with a terminal. The commands are short, and every one gets an explanation. If you have used Moonlight on a laptop or TV before, our Moonlight game streaming setup guide covers that side, and this article focuses on the Pi.
Set aside about 45 minutes. Flashing the OS and updating packages eat most of the clock, while pairing and the first stream take a few minutes.
What the Raspberry Pi price hikes mean for your budget
Raspberry Pi raised prices again on October 1, 2026. The 2GB Pi 5 went from $65 to $77.50, and the 2GB Pi 4 went from $55 to $67.50. Each rose by $12.50, and the company blamed memory costs. Coverage from The Register framed the Pi 4 move as the end of the $35 computer for that memory size, and NeoTeo confirmed the Pi 5 figure. The 1GB models did not change.
| Board and memory | US price after October 1, 2026 | Change |
|---|---|---|
| Raspberry Pi 4, 1GB | $35 | Unchanged |
| Raspberry Pi 4, 2GB | $67.50 | Up $12.50 from $55 |
| Raspberry Pi 5, 1GB | $45 | Unchanged |
| Raspberry Pi 5, 2GB | $77.50 | Up $12.50 from $65 |
| Compute Module 5, 2GB | Not restated in the announcement | Price unchanged |
Those prices are for the boards alone. You still need a power supply, a cable, storage, and ideally a case with cooling. Check current accessory prices at your reseller, because this table does not cover them.
What does this mean for a streaming client? A game stream is one video feed plus a controller link. The client needs little memory, so the smaller models make sense here. A 1GB Pi 4 at $35 is the cheapest sane entry. The 1GB Pi 5 at $45 costs $10 more and gives you the newer, faster chip. The 2GB boards now cost enough that the jump to a Pi 5 2GB, only $10 above the Pi 4 2GB, feels easy to justify.
If you already own a board, use it. You may have a Pi from an older project. Our Pokémon on Raspberry Pi 5 RetroPie guide is a good example of a build that can share the same hardware, since you can keep a second microSD card for streaming and swap cards when you want retro games instead.
My recommendation is simple. Buy a Pi 5 if you must buy. Reuse a Pi 4 if you have one. Treat Pi 2 and Pi 3 boards as a curiosity that now has official support, not as the path you plan around.
Moonlight and Sunshine versus hosted free cloud gaming
Self-hosting is not the only way to play without paying a subscription. It helps to see the whole field before you commit an evening to it. The state of hosted cloud gaming shifted this month, so here is where things stood on October 26, 2026.
| Option | Cost | What you supply | Status on October 26, 2026 |
|---|---|---|---|
| Moonlight plus Sunshine on a Pi | $0 for software | Gaming PC, home network, a Pi | Active and free |
| Xbox Cloud Gaming prepaid Cloud Playtime | $3.99 for 10 hours, $7.99 for 25 hours, $11.99 for 50 hours | Xbox account and a supported device | Insider test that began October 21 |
| Xbox Game Pass cloud play | Plan price, with monthly cloud allowances that differ by tier | Xbox account and a supported device | Cloud-playable tiers named Essential and Premium, plus a third top tier |
| GeForce NOW paid memberships | Performance, a higher tier, and a Day Pass | NVIDIA account and a supported device | NVIDIA’s membership page updated October 20 |
| Amazon Luna | Luna Standard and Luna Premium subscriptions | Amazon account and a supported device | Plan names listed on Amazon’s support page |
Xbox is moving away from a Game Pass-only model. Microsoft said on October 21 that Insiders without Game Pass can test prepaid Cloud Playtime packs and can also test free cloud gaming with ads. The packs, per reporting from The Verge and Gaming Route, cost $3.99 for 10 hours, $7.99 for 25 hours and $11.99 for 50 hours. Reports say a wider rollout is planned for November, but that is not confirmed. Anyone outside the Insider program cannot count on any of it yet.
NVIDIA’s own pages tell a similar story of change. The membership page fetched on October 26 names Performance and a higher paid tier plus a Day Pass. We could not confirm a no-cost GeForce NOW tier on those pages, so check NVIDIA’s sign-up flow for your region before you plan around one. Our guide to the GeForce NOW free tier and Steam streaming covers how that route worked when the free tier was documented.
The self-hosted route avoids that churn. Nobody can change your plan, cap your hours, or add ads to a stream that comes from your own PC. The price is hardware you already own and a bit of setup. A write-up from Self Host Picks that calls Sunshine a self-hosted alternative to Shadow PC makes the same argument from the subscription side.
Be clear about the limit, though. Sunshine is not a paid cloud gaming service. The games run on your host PC, and Moonlight on the Pi only receives the stream. When your PC is off, there is no cloud. That tradeoff is the heart of the decision.
The 13 steps fall into four phases. Phase 1 prepares the host PC in Steps 1 to 4. Phase 2 prepares the Pi in Steps 5 to 7. Phase 3 pairs the two and starts a stream in Steps 8 to 10. Phase 4 tunes the network, writes the launcher, and automates startup in Steps 11 to 13.
You can finish Phase 1 and Phase 2 in any order. Do them one at a time if you only have a single keyboard. Keep both machines on the same network until the very end.
Phase 1: prepare the host PC (Steps 1 to 4)
Step 1: Record the host’s address and MAC
Your gaming PC needs a fixed address so the Pi can always find it. Log in to your router and reserve a DHCP address for the PC, or set a static one. Then record the IP and the MAC address, because the launcher script will use the MAC to wake the machine.
On Windows, open PowerShell and run this command:
Get-NetAdapter | Where-Object Status -eq 'Up' | Select-Object Name, MacAddress, LinkSpeed
Get-NetIPAddress -AddressFamily IPv4 | Where-Object { $_.IPAddress -like '192.168.*' } | Select-Object InterfaceAlias, IPAddressOn Linux, use these two commands instead:
ip -br link
ip -4 -br addrExample output on Windows (yours will differ):
Name MacAddress LinkSpeed
---- ---------- ---------
Ethernet AA-BB-CC-11-22-33 1 Gbps
InterfaceAlias IPAddress
-------------- ---------
Ethernet 192.168.1.50Write down both values. This guide refers to the host’s IP address and uses AA:BB:CC:11:22:33 for the MAC. Also switch on Wake-on-LAN in your BIOS and in the network adapter’s power settings if you want the Pi to wake the PC later. You can skip that part and still finish the tutorial.
Step 2: Install Sunshine on the host
Open the LizardByte/Sunshine releases page on GitHub and download the latest stable build for your platform. The project publishes packages for Windows, macOS, Linux and FreeBSD, and its repository showed several dated builds in the middle of October 2026. Pick a stable release, not a pre-release, unless you have a reason to test.
The Sunshine documentation lists every supported install method. On Windows, run the installer and accept the firewall prompts. On Ubuntu or Debian, install the matching .deb file like this:
sudo apt install ./sunshine-ubuntu-22.04-amd64.deb
systemctl --user enable --now sunshineThe exact file name depends on your distribution and the release you downloaded, so adjust the first line. The package installs a user service named sunshine, and the second line starts it. If you prefer a longer visual walkthrough of the host side, our Sunshine setup guide for streaming PC games to any TV goes deeper on Windows.
One note from the project’s September 6 release notes: Sunshine moved to a new input layer called libvirtualhid, and some Windows gamepad and Raw Input features reportedly need a separately installed Virtual HID Driver. If your controller does nothing later, come back to this point and read the release notes for your build.
Step 3: Create your Sunshine login
Sunshine ships with a web interface that listens on port 47990. Open a browser on the host and go to https://localhost:47990. Your browser will warn about a self-signed certificate. That is expected, so proceed past it.
The first visit asks you to create a username and password. Choose a strong password, because this panel controls pairing and applications. Never forward port 47990 through your router. Anyone who reaches that page and guesses the password can reconfigure your PC.
After you sign in, open the Configuration page and leave most defaults alone. One setting is worth a look. If your GPU supports HEVC encoding, leave HEVC support at its default so the Pi can use it later.
Step 4: Verify the encoder and the app list
Open the Applications tab. A fresh install normally lists a Desktop entry and a Steam Big Picture entry. Desktop streams everything you see on the host’s screen. Steam Big Picture launches Steam in controller mode, which is the nicest way to browse a library from a couch.
Now open the Troubleshooting tab and read the logs. You are looking for a line that shows Sunshine found a working video encoder. A healthy start looks roughly like this (example only, your GPU and format will differ):
Info: Found H.264 encoder: h264_nvenc [nvenc]
Info: Found HEVC encoder: hevc_nvenc [nvenc]
Info: Configuration UI available at [https://localhost:47990]If the log shows only a software encoder, update your graphics driver and restart Sunshine. A software encode can work, but it burns CPU you want for the game. Fix this now, because nothing you do on the Pi can repair a weak encoder.
Phase 2: prepare the Raspberry Pi (Steps 5 to 7)
Step 5: Flash Raspberry Pi OS
On any computer, install Raspberry Pi Imager and insert your microSD card. Choose your Pi model, then pick Raspberry Pi OS (64-bit) with the desktop. Before you write, open the customisation settings and fill in these fields:
- Hostname:
gamepi - Username and password: choose your own, and this guide uses
player - Wi-Fi: skip this if you plan to use Ethernet, which you should
- Services: enable SSH so you can paste commands from your main computer
Write the card, move it to the Pi, connect the HDMI cable, plug in Ethernet, and apply power. The first boot takes a minute or two while the system resizes the card. Because the Pi will sit next to a TV, this is also the time to check that the picture fills the screen. Fix overscan in the display settings if the edges are cut off.
Step 6: Update the system and test audio
Open a terminal on the Pi, or SSH in from your main computer with ssh [email protected]. Update everything before installing Moonlight. Package updates carry graphics and video decoder fixes, and Moonlight leans on both.
sudo apt update
sudo apt full-upgrade -y
sudo rebootAfter the reboot, confirm that audio reaches the TV. Raspberry Pi OS on recent releases uses PipeWire, so this command lists the available outputs:
wpctl statusLook for an HDMI sink in the output and make sure it is the default. If you own a Pi 2 and want 1080p at 60 frames per second, the Moonlight release notes say you must overclock the GPU. Open /boot/firmware/config.txt with sudo nano and add this line at the bottom:
gpu_freq_min=400Skip that line on a Pi 4 or Pi 5. Those boards do not need it, and extra overclocking without cooling only adds heat.
For a longer-lived install, add a case with passive or active cooling. A streaming client runs its video decoder for hours, and a hot board throttles in exactly the way that looks like network lag.
Step 7: Install Moonlight
Moonlight publishes a package repository for Raspberry Pi OS. The following command adds it and installs the client. It reads your OS codename automatically.
curl -1sLf 'https://dl.cloudsmith.io/public/moonlight-game-streaming/moonlight-qt/setup.deb.sh' | distro=raspbian codename=$(. /etc/os-release && echo "$VERSION_CODENAME") sudo -E bash
sudo apt install -y moonlight-qtCheck which version you got:
apt-cache policy moonlight-qtExample output (yours will differ):
moonlight-qt:
Installed: 6.2.0
Candidate: 6.2.0If the first command complains that your codename is unsupported, use Flatpak instead. Run sudo apt install -y flatpak, add the Flathub remote, then install the Moonlight package from Flathub. The Moonlight wiki page for Raspberry Pi lists the current methods, and it is the page to trust if this article ever falls behind.
Aim for version 6.2.0 or newer. That release reportedly fixed three security issues (CVE-2026-33546, CVE-2026-33547 and CVE-2026-41210), so an older client is a poor idea even on a home network.
Phase 3: pair and stream (Steps 8 to 10)
Step 8: Pair the Pi with the host
Pairing proves to Sunshine that your Pi is allowed to connect. Run the pairing command on the Pi and give it the host address:
moonlight pair 192.168.1.50The terminal prints a four-digit PIN and waits. Go to the Sunshine web interface on the host, open the PIN tab, type the PIN, and give the device a name such as gamepi. Within a second or two the Pi reports success.
Authenticating with host...
Please enter the following PIN on the target PC: 4821
Pairing successfulYou only pair once per Pi. Sunshine remembers the certificate, so later launches connect without a PIN. If you would like a second walkthrough of the same pairing dance, the Sunshine game streaming setup guide shows the host-side screens in more detail.
Pairing fails when the two devices sit on different subnets, such as a guest Wi-Fi network and your main LAN. Put both on the same network for this step. You can lock things down again later.
Step 9: Start your first stream
List the applications Sunshine offers, then start the Desktop entry at 1080p and 60 frames per second. The flags below are a good first attempt on a Pi 5.
moonlight list 192.168.1.50
moonlight stream 192.168.1.50 "Desktop" --1080 --fps 60 --bitrate 20000 --video-codec HEVCStart with a moderate bitrate on wired Ethernet and adjust in Step 11. On a Pi 4, try H.264 first, because that board has a hardware path for it. On a Pi 5, stick with HEVC, since its video hardware is built around that codec and H.264 may fall back to software decoding. Run moonlight help stream to confirm the flag names on your version.
Once the picture appears, press Ctrl+Alt+Shift+S to show the performance overlay. It reports the resolution, frame rate, codec, decoder type, and network figures. A healthy overlay looks like this (example only):
Video stream: 1920x1080 60.00 FPS (Codec: HEVC)
Incoming frame rate from network: 60.00 FPS
Frames dropped by your network connection: 0.00%
Average network latency: 2 ms (variance: 1 ms)
Average decoding time: 3.10 msCheck the decoder line first. If it says software decoding, the Pi is working too hard and will stutter. Press Ctrl+Alt+Shift+Q to quit the stream when you finish.
Step 10: Connect a controller
Plug a USB gamepad into the Pi, and Moonlight picks it up through SDL with no extra setup. Confirm the system sees it with evtest:
sudo apt install -y evtest
sudo evtestFor a Bluetooth pad, put the controller in pairing mode and use bluetoothctl:
bluetoothctl
power on
agent on
scan on
pair AA:BB:CC:DD:EE:FF
trust AA:BB:CC:DD:EE:FF
connect AA:BB:CC:DD:EE:FF
exitReplace the address with the one that scan shows for your controller. Some Xbox One pads misbehave over Bluetooth on Linux until you disable ERTM, a known workaround. If yours disconnects, run echo 1 | sudo tee /sys/module/bluetooth/parameters/disable_ertm and pair again.
Start a stream and move the sticks inside a game or the Steam Big Picture menu. If the host ignores the gamepad while the Pi sees it, the cause is on the host side. Revisit the virtual gamepad note from Step 2.
Phase 4: tune, script and automate (Steps 11 to 13)
Step 11: Test and tune the network
A Moonlight session lives or dies on the network, so measure it before you blame software. NVIDIA’s own system requirements for GeForce NOW recommend a wired Ethernet connection or a 5 GHz Wi-Fi router, and the company asks for latency under 80 ms to its data center. Your LAN should beat that by a wide margin, so aim for single-digit milliseconds.
Install two small tools on the Pi and run iperf3 as a server on the host. On Windows, download an iperf3 build. On Linux, install it from your package manager and run iperf3 -s.
sudo apt install -y iperf3 iw
ping -c 20 192.168.1.50
iperf3 -c 192.168.1.50 -u -b 40M -t 10Example output (yours will differ):
20 packets transmitted, 20 received, 0% packet loss, time 19027ms
rtt min/avg/max/mdev = 0.612/0.894/2.101/0.301 ms
[ ID] Interval Transfer Bitrate Jitter Lost/Total Datagrams
[ 5] 0.00-10.00 sec 47.7 MBytes 40.0 Mbits/sec 0.112 ms 0/34550 (0%)Zero loss and low jitter at 40 Mbps tell you a 20 Mbps stream has plenty of room. If you see loss, switch to Ethernet or move the access point closer. On Wi-Fi, also turn off power saving, which adds jitter:
sudo iw dev wlan0 set power_save offThat setting resets on reboot. To make it permanent with NetworkManager, run nmcli connection modify "YourWiFiName" 802-11-wireless.powersave 2. For a deeper latency measurement that works against hosted services as well, see our free cloud gaming lag test in Python, and compare the numbers from your Pi with the numbers from a laptop on the same desk.
Raise the bitrate in steps of 5 Mbps while you watch the overlay. Stop when you see dropped frames, then back off one step. Most people settle somewhere that looks clean without saturating the link.
Step 12: Write the launcher script
Typing flags every time gets old. Make a small config file and a script that does four jobs. It reads settings, wakes the host if it is asleep, waits until Sunshine answers, and starts the stream. Create the folders first:
mkdir -p ~/bin ~/.config/gamestream
sudo apt install -y wakeonlanThen save this as ~/.config/gamestream/gamestream.conf:
HOST_IP=192.168.1.50
HOST_MAC=AA:BB:CC:11:22:33
APP_NAME="Steam Big Picture"
RESOLUTION=--1080
FPS=60
BITRATE=20000
CODEC=HEVC
WAIT_SECONDS=90And save this as ~/bin/gamestream.sh:
#!/usr/bin/env bash
set -u
CONF="$HOME/.config/gamestream/gamestream.conf"
LOG="$HOME/.config/gamestream/gamestream.log"
if [ ! -f "$CONF" ]; then
echo "Missing $CONF" | tee -a "$LOG"
exit 1
fi
. "$CONF"
log() { echo "$(date '+%F %T') $*" | tee -a "$LOG"; }
host_up() {
ping -c 1 -W 1 "$HOST_IP" >/dev/null 2>&1
}
if ! host_up; then
log "Host $HOST_IP is not answering, sending Wake-on-LAN"
wakeonlan "$HOST_MAC" >/dev/null
fi
waited=0
until host_up; do
if [ "$waited" -ge "$WAIT_SECONDS" ]; then
log "Host did not wake within $WAIT_SECONDS seconds, giving up"
exit 2
fi
sleep 3
waited=$((waited + 3))
done
log "Host is up after about $waited seconds"
# Give Sunshine a moment to start after boot
sleep 10
log "Starting stream: $APP_NAME at $RESOLUTION $FPS fps, $BITRATE kbps, $CODEC"
exec moonlight stream "$HOST_IP" "$APP_NAME" "$RESOLUTION" --fps "$FPS" --bitrate "$BITRATE" --video-codec "$CODEC"Make it executable and run it by hand once:
chmod +x ~/bin/gamestream.sh
~/bin/gamestream.shIf the host is awake, you should see a log line and then the stream opens. If you put the PC to sleep first, you should see the Wake-on-LAN line, a short wait, and then the stream. When the stream ends, the script exits and returns you to the desktop.
Step 13: Start the stream automatically at boot
For a console feel, let the Pi log in on its own and start the script. Enable desktop autologin first. This command is the scripted equivalent of the raspi-config menu option:
sudo raspi-config nonint do_boot_behaviour B4Then find out which session your Pi runs, because the autostart location depends on it:
echo "$XDG_CURRENT_DESKTOP"Recent Raspberry Pi OS releases use the labwc compositor. If your output mentions labwc, create or edit ~/.config/labwc/autostart and add one line:
/home/player/bin/gamestream.sh &If your session runs Wayfire instead, open ~/.config/wayfire.ini and add the script under an autostart section:
[autostart]
gamestream = /home/player/bin/gamestream.shReboot the Pi. Within about a minute it should wake the host if needed, connect, and land on your Steam Big Picture screen. You now have a dedicated cloud gaming box that costs nothing per month.
The complete working project
Here is the whole build in one place, so you can check that nothing is missing. Everything lives under the home folder of the user you created in Step 5.
/home/player/
bin/
gamestream.sh launcher with Wake-on-LAN and retries
netcheck.sh quick network health check
.config/
gamestream/
gamestream.conf host address, MAC, app and stream settings
gamestream.log created automatically
labwc/
autostart one line that runs gamestream.shYou already created three of these files. The last piece is a network check script that you can run any time something feels off. It pings the host, reports loss and latency, and shows the Wi-Fi link if one exists. Save it as ~/bin/netcheck.sh:
#!/usr/bin/env bash
set -u
. "$HOME/.config/gamestream/gamestream.conf"
echo "== Ping to $HOST_IP (30 packets) =="
ping -c 30 -i 0.2 "$HOST_IP" | tail -n 2
if command -v iw >/dev/null 2>&1 && iw dev wlan0 link 2>/dev/null | grep -q Connected; then
echo "== Wi-Fi link =="
iw dev wlan0 link | grep -E 'SSID|freq|signal|tx bitrate'
else
echo "== Wi-Fi not in use =="
fi
echo "== Decoder hint =="
echo "During a stream press Ctrl+Alt+Shift+S and confirm hardware decoding."Make it executable with chmod +x ~/bin/netcheck.sh and run it:
~/bin/netcheck.shExample output on a wired Pi (yours will differ):
== Ping to 192.168.1.50 (30 packets) ==
30 packets transmitted, 30 received, 0% packet loss, time 5812ms
rtt min/avg/max/mdev = 0.588/0.801/1.712/0.226 ms
== Wi-Fi not in use ==
== Decoder hint ==
During a stream press Ctrl+Alt+Shift+S and confirm hardware decoding.The project is deliberately small. It has no daemon, no database and no extra services. Each file does one job, and you can read all of them in five minutes. That simplicity pays off when something breaks at 11 p.m. and you only want to play.
Common pitfalls to avoid
Most failed Moonlight installs trace back to a handful of avoidable mistakes. Read this list before you start troubleshooting, because the cure is often a setting you already know about.
- Pairing across different networks. A guest network, a VLAN, or a mesh node in router mode puts the Pi and the PC on different subnets. Discovery breaks and pairing fails. Pair on the main LAN first.
- Trusting Wi-Fi by default. A 2.4 GHz connection or an aggressive power-saving mode produces stutter that looks like a software bug. Use Ethernet. If you cannot, use 5 GHz and turn power saving off.
- Letting the Pi decode in software. Choosing a codec the Pi cannot accelerate pins the CPU and drops frames. Check the overlay’s decoder line and switch codecs if it says software.
- Forgetting the host display. Some hosts return a black screen when no monitor is attached or the display is asleep. A cheap HDMI dummy plug or a virtual display fixes this on headless machines.
- Letting the address change. If your router hands the host a new IP after a reboot, your script points at nothing. Reserve the address in the router, as in Step 1.
- Mixing very old and very new builds. Newer features such as end-to-end stream encryption reportedly need a recent Sunshine release paired with a recent Moonlight, so update both sides together.
- Overclocking without cooling. The Pi 2 overclock is only for Pi 2 boards, and any extra clock speed needs a heatsink. A throttled board stutters in ways that mimic a bad network.
- Exposing the Sunshine panel to the internet. Port 47990 is an administration interface. Reach it only from your LAN or through a VPN.
Troubleshooting: 12 problems and fixes
Work through these in order of how often they appear. Each fix assumes you followed the steps above.
- Pairing fails or the PIN is rejected. Confirm both devices share a subnet, enter the PIN within the time limit shown, and run the pair command again to get a fresh PIN. Restart Sunshine if the PIN tab does not respond.
- Moonlight says the computer is offline. Check that Sunshine is running, that the host firewall allows it, and that the IP in your config is correct. Try
ping 192.168.1.50from the Pi first. - Black screen after connecting. The host display may be off, locked, or missing. Wake the display, attach a dummy plug, or choose the Desktop app to see what the host sees. Also read the Sunshine log for encoder errors.
- Stutter and dropped frames. Lower the bitrate in 5 Mbps steps, move to Ethernet, and confirm hardware decoding in the overlay. Run
netcheck.shto rule out loss. - No sound. Run
wpctl statuson the Pi and set the HDMI output as default. On the host, make sure Sunshine’s audio sink is the one your game uses. - Controller not detected. Run
sudo evtestto confirm Linux sees it. For Bluetooth pads, try the ERTM workaround from Step 10. If the Pi sees the pad and the game does not, check the host’s virtual gamepad driver. - Stuck keys or odd mouse movement. Quit the stream with Ctrl+Alt+Shift+Q and start again. Release modifier keys before launching. If the problem returns, test with a different keyboard.
- Moonlight crashes at launch or shows a renderer error. Update to 6.2.0 or newer, because the project’s repository showed fixes for renderer error handling in late October. As a test, force software decoding with
--video-decoder softwareto see whether the hardware path is the cause. - The repository script reports an unsupported codename. Install Moonlight through Flatpak, as described in Step 7, instead of fighting the apt repository.
- Streaming works at home and fails away from home. Do not open router ports casually. Use a VPN such as Tailscale on both machines, then point the config at the host’s VPN address.
- Sunshine misbehaves after a host update. A GitHub issue reported Windows-host crashes on one September build and said rolling back to an older build restored streaming. Check the issues page for your build and roll back if others report the same crash. The Apollo fork is the main alternative host if you need one.
- Wake-on-LAN does nothing. Enable the feature in the BIOS and in the adapter’s power settings, and note that many PCs only wake from sleep, not from a full shutdown. Wi-Fi hosts rarely support it. Use Ethernet on the host.
Advanced tips
Once the basics run, a few upgrades add real value. None of them are required, and each can be added separately.
Stream from anywhere with a VPN. Install Tailscale on the host and on the Pi, then replace the host IP in gamestream.conf with the VPN address. The Pi can then reach your PC from a hotel or a relative’s house without opening any router ports. Expect higher latency than on your LAN, so lower the bitrate.
Keep two profiles. Copy the config file to gamestream-lan.conf and gamestream-away.conf, then let the script take a profile name as an argument. A 20 Mbps profile for home and a 10 Mbps profile for travel cover most situations.
Rent the host instead of owning it. If your gaming PC lives far away or you have none, you can run Sunshine on a rented GPU machine and keep the same Pi client. Our Sunshine and Moonlight on AWS G7 guide covers that route, though rented GPUs cost real money by the hour, so it is no longer free.
Use the app list as a menu. Add more entries in Sunshine’s Applications tab, such as a launcher for a specific emulator or a separate Steam profile. Then pass the app name as an argument to the script. A family member can pick a game by name without touching a keyboard.
Log boots to find slow starts. The script writes timestamps to gamestream.log. After a week, read the file and look at how long the host took to wake. If it is slow, add a longer wait or move the host to a faster sleep state.
Update both sides on a schedule. Moonlight updates through apt, so a weekly sudo apt update && sudo apt upgrade keeps the client current. Sunshine updates by installing a new package on the host. The project ships builds frequently, so check the release notes before you jump to a pre-release.
Plan for older boards. If you try a Pi 2 or Pi 3 because Moonlight 6.2.0 now supports them, expect to lower your sights. The release notes say a Pi 2 needs the GPU overclock for 1080p at 60 frames per second, so start with 720p at 30 frames per second and climb from there.
Security and privacy notes
A game stream is a remote desktop with extra steps, so treat it like one. Anyone who pairs with your Sunshine host can see and control that PC. Keep these habits.
Pair only devices you own. Review the paired device list in the Sunshine web interface every few months and delete entries you do not recognize. Choose a long, unique password for the panel. Keep port 47990 off the internet, and reach the host remotely only through a VPN.
Keep software current. Moonlight 6.2.0 reportedly closed three security issues. Moonlight release notes also describe end-to-end stream encryption support when the client pairs with Sunshine v0.22 or a current nightly build. Running recent builds on both ends gets you those protections, and old clients leave them off the table.
Finally, remember that the stream carries your screen. If you play on a shared network, such as a dorm or a rental, a VPN is a smart extra layer even though the stream itself is encrypted in recent builds.
When a hosted service makes more sense
Self-hosting is not for everybody. If you have no gaming PC, if your PC is a thin laptop, or if you travel with a device that cannot run a VPN client, a hosted service solves the problem more directly.
Look at the facts as of October 26, 2026. Xbox is testing free cloud gaming with ads and prepaid Cloud Playtime for Insiders, and the broader rollout is reportedly planned for November. Our guide to Xbox Cloud Gaming free without Game Pass tracks what works today. NVIDIA lists paid memberships and a Day Pass, and NVIDIA said GeForce NOW added DLSS 4.5 controls on October 15 plus Call of Duty: Modern Warfare 4 at launch. Amazon’s support pages list Luna Standard and Luna Premium and mention Chromebook access through Chrome.
A Pi works with some of these too, but through a browser or an app, not through Moonlight. The cleanest rule is this. Choose self-hosting when you already own a capable PC and enjoy tinkering. Choose a hosted service when you want zero hardware and accept caps, queues, or a bill. For more picks across both camps, browse our gaming guides.
Frequently asked questions
Is Moonlight streaming really free?
The software is free. Moonlight and Sunshine are open-source projects with no subscription, license fee, or hour cap. You do pay for what the software needs, which means a gaming PC, a network, and a client device such as a Raspberry Pi.
Which Raspberry Pi should I use as a Moonlight client?
A Raspberry Pi 5 is the best choice for a new build, and it stays in production until at least January 2036 according to Raspberry Pi. A Pi 4 works well and costs $35 for the 1GB model after the October 1, 2026 price changes. Pi 2 and Pi 3 are officially supported as of Moonlight 6.2.0, but expect lower settings.
Can a Raspberry Pi 2 or Pi 3 stream at 1080p?
The Moonlight 6.2.0 release notes say a Pi 2 needs the line gpu_freq_min=400 in its boot configuration to reach 1080p at 60 frames per second. For a Pi 3, start with 720p, test the stream overlay, and raise the resolution only if the frame rate holds.
Is this the same as cloud gaming?
Not quite. Commercial cloud gaming runs your game in a data center that someone else owns. Moonlight with Sunshine runs it on your own computer and streams it to the Pi. The experience looks similar from the couch, but the economics and the failure modes differ.
Do I need Ethernet, or is Wi-Fi enough?
Ethernet is the safe answer. NVIDIA’s own GeForce NOW requirements recommend wired Ethernet or a 5 GHz Wi-Fi router, and the same logic applies to a local stream. Wi-Fi can work well on 5 GHz with power saving turned off, but test it with the steps above before you rely on it.
Is it safe to leave Sunshine running all the time?
Yes, if you keep it off the open internet. Use a strong password for the web panel, update regularly, pair only your own devices, and use a VPN for remote play. Never forward the administration port through your router.
What if Moonlight lags even on Ethernet?
Check the overlay first. If the decoder line says software, change the codec or update the Pi’s packages. If decoding is fine, lower the bitrate and look at host load. A game that pegs the host GPU can starve the encoder, which looks like network lag but is not.
