Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
In this guide:
- Quick Setup Instructions
- Streaming over the Internet
- Moonlight Client Setup Instructions
- Touchscreen Controls for Android or iOS
- Using a gamepad connected to the PC instead of the streaming device
- Adding custom programs that are not automatically found
- Using Moonlight to stream your entire desktop
- NVIDIA GeForce GTX 600+ series GPU (GT-series and AMD GPUs aren't supported by NVIDIA GameStream)
- NVIDIA GeForce Experience (GFE) 2.1.1 or higher
- 720p or higher display connected to the PC
Quick Setup Instructions
On your gaming PC, install the GeForce Experience software from geforce.com. The PC may need a reboot after installation to finish setup.
Start GeForce Experience and click on the Settings "gear" button. Then choose the SHIELD option. Make sure the GameStream switch is in the "on" position (green). If the SHIELD tab is not present, see the troubleshooting steps here.
Start Moonlight and make sure your client is connected to the same network as your PC. In most cases, your gaming PC will show up automatically in the PC list after a few seconds. Click the entry in the PC list to start pairing.
If your PC doesn't appear automatically for some reason, click the plus button and add your PC using its local network IP address. To find your gaming PC's local network address:
Click on the Start menu, type cmd, and press Enter/Return
Type ipconfig and press Enter/Return
Try typing the number after "IPv4 Address" into Moonlight's Add PC dialog. Try all of the listed addresses until one of them works. Addresses starting with 192.168 are typically the correct ones.
On your PC, enter the PIN displayed in Moonlight and accept the pairing dialog. If you don't see a pairing dialog, try the troubleshooting steps here.
Try streaming a game or app to make sure everything is working.
- By default, GeForce Experience will reserve Player 1 for the Moonlight client's gamepad. If you want to use a gamepad connected directly to your gaming PC, follow these steps.
- If you want to stream in 4K resolution, you must check the "Allow experimental features" checkbox on the GeForce Experience settings page.
- If you can't successfully stream at all, try the troubleshooting steps here.
If you are not able to stream when connected to the same network as your gaming PC, you may need to add firewall rules to stream successfully. First, try disabling your firewall software (usually Windows Firewall or a firewall integrated into your anti-virus software) to confirm it's a firewall-related problem.
GeForce Experience should create rules for Windows Firewall automatically, but in the event that they don't work, you can create the rules required for streaming by using the following steps:
- Open a Command Prompt or PowerShell window as administrator
- Run the following 2 commands:
- netsh advfirewall firewall add rule name="GameStream UDP" dir=in protocol=udp localport=5353,47998-48010 action=allow
- netsh advfirewall firewall add rule name="GameStream TCP" dir=in protocol=tcp localport=47984,47989,48010 action=allow
- Ensure your PC now appears online in Moonlight
Other firewall software
For other firewall products, you should follow their instructions to create exceptions for the following ports:
- TCP 47984, 47989, 48010
- UDP 5353, 47998, 47999, 48000, 48002, 48010
Streaming over the Internet
Port forwarding (recommended for most users)
The following ports must be forwarded through your router for streaming to work with the latest version of GeForce Experience:
- TCP 47984, 47989, 48010
- UDP 47998, 47999, 48000, 48002, 48010
If your port forwarding setup just stopped working recently, check that TCP 48010 is forwarded. It is newly required with GeForce Experience v3.12.
Once you've set up port forwarding, you'll need to add your PC again from the Moonlight app so it can learn your router's external IP address. Go to http://www.whatsmyip.org/ from your gaming PC, then enter the IP address you get there into Moonlight. If you don't get an error, you should be all set.
IPv6 (certain ISPs only)
If you are lucky enough to have native IPv6 connectivity to your host PC and client device on the networks you'd like to stream on, you may opt to use IPv6 instead of port forwarding. This has the advantage of allowing you to stream from multiple PCs behind a single Internet connection, which is not possible with port forwarding. This option is only recommended for those very familiar with network administration. You may combine these steps with port forwarding above to stream over IPv4 or IPv6, depending on your client's connectivity.
- Navigate to http://test-ipv6.com/ on both your host PC and client device and confirm they both score 10/10 on the networks you will be streaming from. You may need to disable Chrome's Data Compression option to get accurate results on mobile.
If your host PC doesn't score 10/10, you won't be able to use this method for streaming over the Internet with your ISP.
If your client device doesn't score 10/10 but your host PC does, you won't be able to stream over IPv6 on the current network but another network may work.
Install the GameStream IPv6 Forwarder on your host PC.
Configure your router's IPv6 firewall (typically separate from the IPv4 firewall/port forwarding) to allow the ports listed in the section above.
In Moonlight, click Add PC and type the IPv6 address of your PC. Your PC should appear online (or remain online, if you already had IPv4 connectivity to it).
All officially supported Moonlight clients (iOS, PC, Android) support streaming from servers over IPv6. Unofficial clients (Embedded, Vita) may not.
If your PC doesn't appear online outside your network or you get an RTSP handshake failure error, check that the TCP ports are correctly forwarded. Also ensure you've typed your server PC's external IP address into the Add PC page to bond your external IP address with your PC in Moonlight.
If you have no audio or video when streaming from outside your network, check that the UDP ports above are forwarded correctly. Make sure they are forwarded as UDP, not TCP in your router settings.
To find the external IP address of your server, when connected to your home network, use a service like http://whatip.me/ on your server PC to determine the IPv4 address another computer uses to talk to you. Ensure you always use your IPv4 address not your IPv6 address (unless you're following the IPv6 steps above).
To stream over the Internet, in your client: If your PC already appears online when connecting over the Internet, you're all set. If it doesn't, tap on the add button in Moonlight, then enter in the IP address (or hostname, if you set one up for your router). Your IP address should look something like 22.214.171.124. If you see an address with semi-colons, that's an IPv6 address and won't work for Moonlight (unless you've followed the IPv6 steps above). If your PC still won't come online, try the troubleshooting steps here.
Note: Some Internet Service providers change the external IP address in use by any given subscriber on a regular basis. Since Moonlight needs to connect to the right IP address, this change can cause problems for Moonlight. Using a dynamic DNS service like No-IP will give Moonlight a consistent name to use for connecting, even if the IP address that's associated with that name changes a lot.
Moonlight Client Setup Instructions
Android: An Android device running Android 4.1 (Jelly Bean) or newer. Newer and "flagship" devices with higher processor speeds are more likely to be able to handle Moonlight well by using the hardware video system on the device to produce smooth streaming without video stuttering or freezing.
iOS: An iOS device running iOS 8.0 or later.
PC: Windows 7+, macOS 10.11+, or Linux. Your PC should be new enough that it supports hardware-accelerated H.264 video decoding, otherwise it will have to use CPU decoding. Most PCs made since around 2010 should work fine.
ChromeOS: All ChromeOS devices should have the required hardware.
Internet and Network Requirements
To have a good experience, you need a mid to high-end wireless router with a good wireless connection to your client device (5 Gigahertz (GHz) highly recommended, Wireless-N (802.11n) or better strongly recommended) and a good connection from your PC server to your router (Ethernet/wired connections highly recommended).
Controls for Android devices
For non-SHIELD devices and devices running Android 7.1 (Nougat) or earlier, using an external mouse with proper mouse capture on Android requires a rooted device. If you want to use an external mouse on your rooted device, you should download "Moonlight for Rooted Devices" on the Play Store or app-root-release.apk from releases. NVIDIA SHIELD devices and Android 8.0 (Oreo) have mouse capturing built-in that Moonlight uses without needing root. Moonlight for Rooted Devices is not available for Android 8.0, since the non-root version contains all features that required root using the new Android Oreo APIs.
To toggle capturing the mouse cursor on Moonlight for Rooted Devices, press Ctrl+Alt+Z.
If you don't have a mouse connected to your Android device, you can emulate one using a game controller. Press and hold the Start button to toggle mouse emulation. When mouse emulation is on, you can use either analog stick to move the cursor. The A button left clicks and the B button right clicks.
Most controllers will work just fine, but the following have been tested:
- Xbox 360 wired/wireless
- Xbox One wired (with Moonlight's built-in driver)
- PS3 wired (with Sixaxis Enabler app) or wireless (with SixAxis Controller app)
- PS4 wired via USB
- MOGA controller (see note below)
- Amazon Fire Game Controller
- Shield integrated controller
MOGA controller users: If your controller has a switch with A and B, it must be switched to B to be used for streaming. If you have no switch, use the MOGA Universal Driver app.
SixAxis controller users: Use SixAxis in "Native Gamepad" mode. The default button mapping needs to be adjusted to match the standard controller layout for streaming.
Controls for iOS devices
Apple devices only natively support MFi controllers. We recommend the "extended layout" controllers which have most buttons present on a typical Xbox 360 controller. Notably lacking are the L3 and R3 buttons and the select button. When using the Auto setting for on-screen controls, an overlay will be displayed containing the buttons that your physical controller is missing.
Controls for PC clients
PC clients support keyboard/mouse input and up to 4 game controllers. On Windows, XInput-compatible gamepads will be mapped automatically. On other systems, you may need to map the controller manually.
To free the mouse cursor from the Moonlight window, press Ctrl+Alt+Shift. To quit streaming, press Ctrl+Alt+Shift+Q.
Touchscreen Controls for Android or iOS
Moonlight for Android and iOS use the touch screen as a way of controlling the mouse cursor. Multi-touch devices can emulate more mouse functions than single-touch devices.
- Swiping across the screen moves the mouse cursor in the direction of the swipe.
- Tap once with one finger to left-click.
- Tap and hold in the same place to start a click and drag. After a short while, swipe the finger to drag in the direction of the swipe.
- Hold one finger down and tap a second finger to right-click.
- Tap with three fingers to open the on-screen keyboard (Android only for now). Only some keyboards work with Moonlight for Android - the Hacker's Keyboard seems to work well for everything but the arrow keys.
Using a gamepad connected to the PC instead of the streaming device
Normally, Moonlight sends controller input from the streaming client which gets sent to the game by GFE. If you want to connect a controller to your PC instead of the streaming device, GFE can cause some problems because the emulated controller still appears to games as controller 1. Luckily there is a workaround for this. You'll need to rename the DLL that Nvidia is using to send controller input so it won't be used anymore. You may have to do the renaming again if GFE does an update, but it should allow you to use your controller normally on games that only support 1 controller.
On GeForce Experience 3.0 and later, rename rxgamepadinput.dll to rxgamepadinput.dll.old in C:\Program Files\NVIDIA Corporation\NvStreamSrv and C:\Program Files (x86)\NVIDIA Corporation\NvStreamSrv.
On older version of GeForce Experience (2.x), rename rxinput.dll to rxinput.dll.old in C:\Program Files\NVIDIA Corporation\NvStreamSrv and C:\Program Files (x86)\NVIDIA Corporation\NvStreamSrv.
Adding custom programs that are not automatically found
You can stream any almost any game or app by adding the EXE file to GFE manually (if it's not found by the automatic app scan). Open GeForce Experience, click the Settings (gear) button, click SHIELD on the sidebar, then click the Add button on the right. Browse to the app or file you want to add and click OK. You can rename the app using the Edit button.
The next time the client opens and displays the App List, the newly added programs and games should be displayed and ready to stream.
If quitting an application doesn't stop Moonlight, press Ctrl+Shift+Alt+Q on Moonlight PC to quit the streaming session. On Moonlight Android and iOS, pressing the home key will switch out of the streaming session. Choose the Quit Session option from the App List to fully quit the streaming session.
Using Moonlight to stream your entire desktop
Follow the steps above for adding a custom program, but for the path use: C:\windows\system32\mstsc.exe
You can rename the remote desktop entry using the edit button. When you click this entry, you will see your full desktop where you can run whatever you want.