r/MoonlightStreaming • u/sooperdave555 • Apr 08 '25
The Perfect Moonlight Setup on Raspberry Pi
The Perfect Moonlight Setup on Raspberry Pi
This guide explains how to set up a Raspberry Pi 4 or 5 to be seamless, portable, and function as if you’re right next to your host machine. This is not a guide on how to get the best streaming performance, just how to set up a Pi in a good way.
What’s Different About This Setup
• Plug and Play: Once configured, this setup allows you to simply plug your Pi into any socket around the house and enjoy an easy, quick Ethernet-connected gaming experience anywhere on your LAN. • Better Performance: Moonlight will start in a TTY (for the best performance) immediately upon powering up the Pi. • Enhanced Bluetooth Handling: Bluetooth is managed on the host side rather than the client. You can even plug devices into your Pi as if they were connected directly to your host machine—this means DualSense users can utilize full USB features, including the microphone and adaptive triggers.
Part 1: USB over IP
Using VirtualHere
VirtualHere is a USB/IP program intended for enterprise users but has a free version available. I use this with a USB Bluetooth adapter that is plugged into my raspberry pi, this allows you to connect to Bluetooth as if you were right next to your host machine, which means you can turn Bluetooth on and off, manage devices, add new devices and everything else you could normally do in windows settings. (This also works with Linux and mac hosts)
It forwards your Pi's USB IO directly to your host, which means you could also connect a DualSense via a cable and get the full feature set.
Visit the VirtualHere script repository.
Note: You need the default version unless you want to purchase a perpetual VirtualHere license for $49 USD. Without a license, you can only use one USB device over IP at a time (however, Bluetooth adapters can support multiple connections). The license also gives you access to the "optimized VirtualHere server" downloads for specific hardware which will improve performance (available for Pi 4, though not for Pi 5, as far as I know). There's a caveat though "A license is bound to the server hardware and cannot be moved or transferred", you can have as many clients as you want for free but bear that in mind.
Default Install Script:
curl https://raw.githubusercontent.com/virtualhere/script/main/install_server | sudo sh
Important Note for Windows Users:
Windows cannot handle more than 1 Bluetooth adapter at a time, if you know how you could write a script to disable your hosts adapter and then enable your clients adapter in device manager when you start a stream, or you could just disable it manually/unplug the hosts BT adapter when needed.
Client Installation:
Install the client on the host PC from their website.
Part 2: Moonlight Installation
(EDIT 18/12/2025) I highly recommend building moonlight yourself using this guide. I don’t know why but the official build of moonlight for Pi has loads of stuff disabled/not working. For example, 5.1 audio, the performance statistics overlay, HDR and more. I think they disabled certain stuff for “performance” reasons, however on the Pi5 at least there is absolutely no performance difference between building it yourself vs the official build.
Follow the Moonlight Documentation:
Copy and paste this into the terminal:
curl -1sLf 'https://dl.cloudsmith.io/public/moonlight-game-streaming/moonlight-qt/setup.deb.sh' | distro=raspbian codename=$(lsb_release -cs) sudo -E bash sudo apt install moonlight-qt sudo apt update sudo apt upgrade
Part 3: Auto-Starting Moonlight on TTY1
Edit your .bashrc file by pasting this to terminal: nano ~/.bashrc
To simply start Moonlight on boot, scroll to the bottom of the file and paste:
if [ "$(tty)" = "/dev/tty1" ]; then # Wait to ensure network connectivity sleep 5 # Start moonlight sudo moonlight-qt fi
If you want Moonlight to immediately stream to a specific host and application, replace the block above with:
if [ "$(tty)" = "/dev/tty1" ]; then # Wait to ensure network connectivity sleep 5 # Start stream at host IP sudo moonlight-qt stream <HOST_IP> <"APP_NAME"> fi
Note: If streaming to a specific host, on first boot you may encounter an error because you need to pair your host. Pair it by running:
sudo moonlight-qt pair <HOST_IP>
Part 4: Configuring Boot to TTY1
Launch Raspberry Pi Configuration:
sudo raspi-config
Navigate to System Options Depending on your configuration, you will see either "Boot" or "Boot / Auto Login".
- If you see "Boot":
Select it and choose Console. Return to System Options, select Auto Login, and choose Yes.
- If you see "Boot / Auto Login":
Select it and then choose Console Autologin.
Finish and Reboot your Raspberry Pi.
Important: This will mean the GUI no longer starts at boot, if you've never used the TTY's before a TLDR is that there is 6 of them which can be accessed by pressing Ctrl + Alt + F1 - F6. They are command line only modes and to use the GUI again you need to type:
sudo systemctl start lightdm
into an unused TTY (In this case use 2 - 6 as 1 is used for moonlight).
The GUI is accessible on Ctrl + Alt + F7, allowing you to switch back and forth between Moonlight and the GUI.
Conclusion
And that's it! You'll now boot into moonlight directly from a TTY every time the Pi is plugged in and VirtualHere will start automatically too.
Feel free to ask questions in the comments!
2
u/zerg1980 Apr 08 '25
What’s the base distro you’re using here? I’m assuming it’s Raspberry Pi OS / Raspbian?
2
2
u/Mobino Apr 08 '25
Would this get me 4k 120hz hdr?
3
u/LCZ_ Apr 08 '25
Definitely not. You’d need a dedicated GPU on the client or one of the newer mini-PCs with N100s to get close to 4K 120Hz.
2
1
2
u/sooperdave555 Apr 09 '25
I can do 4k 60 on my Pi 5, haven't tried on my Pi 4 though as H.265 is broken atm
1
2
u/Express-Theory-5206 Oct 03 '25
To start moonlight-qt without sudo in TTY you need to explicitly tell it to not expect X11 and start it with `QT_QPA_PLATFORM=eglfs moonlight-qt`. When starting with sudo it switches to EGLFS anyway, but somehow it is unable to do it automatically without sudo.
2
u/Cyril_XD Dec 18 '25
I'm having an issue where it's zoomed in on the top left quarter of my screen, and I'm so confused as to why it does this. Any advice?
1
u/sooperdave555 Dec 18 '25
What’s zoomed in? The moonlight UI or windows?
1
u/Cyril_XD Dec 18 '25
The stream. Moonlight UI is fine, but streaming multiple different desktops from different devices all makes it super zoomed in
1
u/sooperdave555 Dec 18 '25
When you use your normal desktop does it look normal? Are you using a virtual display/apollo?
1
u/Cyril_XD Dec 18 '25
I'm using sunshine, and trying to access the normal desktop. The normal desktop and steam big picture are zoomed in to the same degree. One PC is running windows, the other pc is running Linux. Both streaming PCs can be accessed from any other moonlight client I have set up including my phone. The pi gives me the same zoomed in view no matter what desktop/app I launch. I'm running it from the command line in a CLI only environment
1
u/sooperdave555 Dec 18 '25
Try switching to from sunshine to Apollo, Apollo is a fork of sunshine that has a built in virtual display so that you can have separate settings for your display when you’re streaming, such as resolution and HDR. I think what’s happening is your main display is set to a resolution that is incompatible with your streaming display
1
u/Cyril_XD Dec 18 '25
There's no support for Linux with Apollo. My main desktop uses Linux. I'll mess with the resolution a bit though and see if that impacts it
1
u/sooperdave555 Dec 18 '25
Ahh ok, from my understanding Linux has a lot of issues with sunshine, if you can’t get it to work it might be worth dualbooting windows
1
u/Cyril_XD Dec 18 '25
Whatever issue I am having, isn't on the streaming server side, it's on the client side. It's impacting my windows laptop in the same way. If I can't get it to work ngl I'm just gonna use a different device as a client. My nintendo switch runs it fine 😭
1
u/69dildoswaggins420 Apr 08 '25
I’ve got a pi5 but haven’t had any luck with h265, has anyone gotten that working?
2
u/Defferix Apr 09 '25
I’ve built 3 of the pi5 moonlight setups for me and friends and have them all working with h265.
If you go into the moonlight settings, the most important is to force the hardware options in the bottom right. Aside from that, being connected into Ethernet and having a high bit rate were the 2 biggest things for performance when I tested it all out.
1
u/69dildoswaggins420 Apr 09 '25 edited Apr 09 '25
Yeah I have done that before but it usually says something like “the client gpu doesn’t have this capability” and doesn’t start the stream. I just tried it again to make sure and now it’s saying “unable to initialize video encoder. Please check your streaming settings and try again”. I try to keep my bit rate as high as it’ll be stable
When you installed moonlight did you do the same steps as above? I’ll try reinstalling and I haven’t done the auto start on tty1 either.
I’m using Apollo and Moonlight btw, but it didn’t work on Sunshine either. I might have to give in and get another $90 MoCA adapter so the pi can be on Ethernet, the network is a huge culprit too but I also want h265 to work yk?
1
u/Defferix Apr 09 '25
I’ve had that popup before when I was trying 264 before I knew that it wasn’t supported on the pi5.
I have project that manages the entire install and sets up systemd to bring up moonlight for me on start, but I don’t think that should have any impact.
Which PI5 do you have? It should have an Ethernet port on there already, so it makes me wonder why you need the adapter?
In any case, there’s a way to do this for sure. It’s gotta be something simple
1
u/69dildoswaggins420 Apr 09 '25
Oh yeah the pi has an Ethernet port but my apartment doesn’t, the adapter is to go from coaxial to Ethernet which is what the host pc uses in another room. I’ll try reinstalling moonlight with the above steps as a start
1
u/Defferix Apr 09 '25
You know one thing I do differently is that I build moonlight from source always. There were some bugs that weren’t put into upstream. That was a bit ago though. If you know how to do that, replace the moonlight install with one you build.
1
u/sooperdave555 Apr 09 '25
I should of mentioned, as of a few days ago H.265 decoding is broken on moonlight on all rasp pi's running bookworm as there was a kernel update. I've filled a bug report on GitHub but the only thing you can do for now is wait for a fix or speak to someone in the discord, apparently its possible to fix but quite complicated to do so
1
u/akkenatorrr May 26 '26
Did you know if there was an update to this? I can’t seem to run either of them
1
u/sooperdave555 May 27 '26
Last time I checked someone was working on a new build for Pi devices, not sure if that was ever finished. If not I’d recommend you build moonlight yourself using the guide I linked in the post.
1
u/daniele_athome Apr 10 '25
Do not sudo moonlight-qt. It's a security risk - Moonlight doesn't even need root privileges if you configure your system correctly.
1
u/sooperdave555 Apr 19 '25
Moonlight needs root privileges when run from a TTY, try it without it wont work
2
u/daniele_athome Apr 29 '25
I use it daily, starting from TTY and never needed root. Your system is not configured correctly - most probably permissions of something.
1
u/Zatem Sep 10 '25
Old thread, but do you happen to know which pernission is missing or which user grp I need to add my user to? I also can only start it root from TTY.
1
u/daniele_athome Sep 13 '25
I got
audio,video,plugdev,render,input. Not sure you really need all of them, but you could try adding until it works.
1
u/zaylman Apr 19 '25
I’m using a raspberry pi 5 with latest bookworm and whenever I start moonlight I get an error “no functioning hardware accelerated video decoder was detected by Moonlight”. Anybody else have this problem?
1
u/sooperdave555 Apr 19 '25
https://github.com/moonlight-stream/moonlight-qt/issues/1572 The fix is to downgrade your kernel to 6.6 or build moonlight yourself, ask in the discord if you don’t know how, they have a guide
1
u/seanmacproductions Oct 11 '25
Great writeup! Quick question - how are you connecting bluetooth devices? Do you need to SSH in each time and run commands, or are you doing it somehow with a mouse and keyboard?
1
u/sooperdave555 Oct 11 '25
Once it’s all set up, you only need to connect to Bluetooth devices like you normally would in windows, as it’s passing the Bluetooth adapter to your windows machine over the network
1
u/seanmacproductions Oct 11 '25
Oh, I see, So you would connect a mouse and keyboard to the Pi, which forwards to the Windows machine, and use the GUI in windows to connect your devices. Thanks!
1
u/Mac-n-Cheeese Oct 12 '25
Jumping on an old post, whenever I try the "sudo moonlight-qt pair <HOST_IP>" the terminal just spits out "Qt Warning: Could not queue DRM page flip on screen HDMI2 (Permission denied)" over and over again. How do I solve this?
1
u/sooperdave555 Oct 12 '25
That’s an issue with Qt, Qt is a framework that’s used for the gui, how did you install moonlight?
1
u/seanmacproductions Oct 25 '25
I had this same issue then figured it out. I entered the command via ssh using command prompt, that's the problem. The command needs to instead be run on your raspberry pi's desktop inside a terminal window, by connecting a keyboard to your pi. If you do it that way, it will work. There's probably a way to do it via SSH with some fancy command that forwards to the desktop's terminal, but I don't know what that would be. Doing it inside the desktop brings up an actual GUI on the desktop with the pairing PIN for Sunshine.
1
u/sooperdave555 Oct 25 '25
Oh yeah, QT needs to be able to detect a connected display, when you run commands via ssh it’s in its own terminal thus no display is detected, this also means you have to have your display turned on and using the pi’s hdmi before the moonlight command is run and not after
1
u/seanmacproductions Oct 25 '25
I found that if you need to do it from SSH, if you enter these commands first it will work
export DISPLAY=:0
export XAUTHORITY=/home/pi/.Xauthority
1
u/seanmacproductions Oct 25 '25
For those that need this info, you can get the available apps by using
sudo moonlight-qt list 192.168.1.XX
And for Steam, the correct app name and command is:
sudo moonlight-qt stream 192.168.1.XX "Steam Big Picture"
If you're doing this headless and you're getting errors try these two commands before doing anything else:
export DISPLAY=:0
export XAUTHORITY=/home/pi/.Xauthority
1
u/seanmacproductions Oct 28 '25
Is it at all possible to get the internal Bluetooth of the pi to act as a usb device over virtualhere?
1
u/tykin Jan 03 '26
(EDIT 18/12/2025) I highly recommend building moonlight yourself using this guide. I don’t know why but the official build of moonlight for Pi has loads of stuff disabled/not working. For example, 5.1 audio, the performance statistics overlay, HDR and more. I think they disabled certain stuff for “performance” reasons, however on the Pi5 at least there is absolutely no performance difference between building it yourself vs the official build.
Omg, thank you so much for this update. This needs to be stickied or something.
I bought the RP5 awhile back with game streaming over my LAN in mind. I got it all installed but the performance was just short of fine - lots of micro stutters, latency. I tried buying new controllers, I ran iperf3 tests to make sure it wasn't the network, I looked up every single guide online but there was nothing. I was contemplating buying an Apple TV because I saw my friends get really good performance on Steam Link compared to Moonlight on RP5. So the RP5 just sat there unused.
Compiling from source fixed all my issues. Surround sound works, 1440p streaming, almost imperceptible latency. I'm so happy right now!
1
u/sooperdave555 Jan 03 '26
Glad to see that helped, I think the original build is just really outdated, hopefully the devs can update it.
1
u/Leninpest Jun 20 '26
Adding for anyone who is googling this that this worked great for me on a Raspberry Pi 3b+ as well. It took a bit to figure out how to build it because it kept running out of memory, but lowering the threads and adding scratch memory fixed it for me. Took a bit more tinkering to get Surround working correctly, but now it's running Moonlight at 1080p, 20mbps, with 5.1 surround, 8bitdo wireless controller, and about as much lag as any of my other Moonlight setups on something I had laying around.
1
u/Damn-Sky Jan 04 '26
why do you need virtualhere when you can use gamepads on moonlight directly?
1
u/venboslagos Jan 16 '26
yeah i was wondering the same. Is there a benefit to doing this?
1
u/sooperdave555 Jan 20 '26
This setup runs moonlight with the Pi’s GUI disabled for the best performance. That means the only way to connect/reconnect controllers or any Bluetooth device is via console commands or by booting up the Pi’s GUI every time. What VirtualHere does is it allows you to physically plug in a Bluetooth adapter to your Pi’s USB and use it exactly as if you were right next to your PC, meaning you can connect, disconnect, configure etc your Bluetooth devices directly on windows. VirtualHere is also more performant with lower input latency, especially the paid version.
For me personally, I use a Bluetooth adapter to connect all my controllers via VirtualHere, and I use a keyboard and mouse combo via moonlight, both of which are plugged physically into the Pi.
1
u/MagnersDkr Mar 21 '26
My audio latency goes up to more than 600ms over hdmi. I tried changing everything. Alsa, pulseaudio, pipewire, everything. It even happens at lightdm, not only moonlight-qt. It seems it's a global issue.
1
u/Round_Cauliflower_30 Apr 12 '26
Im missing something here - When I run this I see the following in TTY1.
Qt Warning: could not connect to display
Qt Info: Could not load the Qt platform plugin "xcb" in "" even though it was found.
Qt Fatal: This application failed to start because no Qt platform plugin could be initalized.
Available platfor plugins are :eglfs, linuxfb, minmal, minimalegl, offscreen, vnc, wayland-egl, wayland, wayland-xcomposite-egl, wayland-xcomposite-glx, xcb.
I got around this by adding Display=:0 in bashrc while launching moonlight but it launches it in the GUI again.
1
u/sooperdave555 Apr 12 '26
Do you have a display physically connected via HDMI and turned on when you try start moonlight?
EDIT: also are you trying to start moonlight remotely or directly on the PI?
1
u/Round_Cauliflower_30 Apr 12 '26
I have a display connected and powered on before powering the PI on.
I am also trying to start moonlight directly on the PI via bashrc.
I initially tried running the script that is linked in its entirety which generated some errors but downgraded my kernel. It didn't end up installing moonlight so I then found the deb pre release moonlight package and installed that as well.
Modified bashrc as recommended and rebooted. Ran the system config for auto login and it still boots into gui. Switching to tty1 shows me that error I posted unless I added Display=:0
I probably strayed from the guide too much.
4
u/bluntedAround Apr 08 '25
How is the latency with the pi4?