Secure VNC on Raspberry Pi OS: Wayland and Headless¶
For a graphical Raspberry Pi OS desktop, enable VNC with sudo raspi-config and connect from a viewer on the same trusted LAN. If you need access from another network, use a VPN or an SSH tunnel. Do not forward VNC port 5900 from your router to the open internet. Raspberry Pi OS Lite has no desktop to share, so use SSH or install a desktop first.
This guide focuses on securely reaching one existing desktop session and diagnosing a blank VNC view. For comparisons with Connect, RDP, and other remote-desktop methods, read the remote-access overview.
Choose a safe connection path¶
| Situation | Recommended path |
|---|---|
| Viewer and Pi on the same trusted LAN | Enable VNC and connect to the Pi's LAN address. |
| Viewer is away from home | Connect to your private VPN first, then use the Pi's private address. |
| SSH is reachable but no VPN is available | Forward the VNC connection through SSH to a local port on the viewer computer. |
| Browser access is more convenient | Consider Raspberry Pi Connect screen sharing on a supported Wayland desktop. |
| Raspberry Pi OS Lite | Use SSH; VNC needs a graphical desktop session. |
The official Raspberry Pi remote-access documentation describes VNC setup and Connect. Its getting-started guide states that VNC is incompatible with Lite.
1. Confirm that a desktop session exists¶
On the Pi, verify that you installed Raspberry Pi OS Desktop, not Lite, and that a user can log in to the graphical desktop. Check the active session from a terminal inside that desktop:
A Wayland desktop uses the Raspberry Pi OS VNC path for that session. A command run from a separate SSH session may report a different environment, so do not infer the desktop type from the SSH shell alone. If the Pi runs Lite, use the official Desktop package instructions or reimage with Desktop before expecting a VNC screen.
2. Enable VNC with the supported settings tool¶
On the Pi, open:
Choose Interface Options → VNC → Yes. You can also use the desktop's Preferences → Control Centre → Interfaces → VNC switch. These are the paths in the official VNC instructions. Use the menus displayed on your installed release rather than relying on an old numeric menu code.
Find the Pi's LAN address:
From a viewer on the same LAN, connect to that address and authenticate with the account configured on the Pi. If the viewer cannot reach it, first confirm the Pi's desktop is running and that the two devices can communicate over the LAN.
3. Connect from another network without a public VNC port¶
A private VPN is usually easiest for regular remote use. Connect the viewer to the VPN, then point the VNC viewer at the Pi's private VPN address. The Tailscale guide covers one option.
If you already have a trusted SSH path to the Pi, create a local tunnel on the viewer computer:
Keep that SSH process running. In the VNC viewer, connect to local address 127.0.0.1 on port 5901 (the exact port-entry format depends on the viewer). SSH carries the viewer traffic to the Pi's VNC service. If your SSH server is on a different port or requires a particular identity, add your usual SSH options.
An SSH tunnel does not disable the Pi's normal VNC listener on its LAN. Check the bind address and firewall policy separately if LAN exposure matters. Never treat router port forwarding as a substitute for authentication or a private transport.
Black screen or connection failure¶
| Symptom | Likely layer | Check |
|---|---|---|
| VNC viewer cannot reach the Pi | Network or service | Confirm the private address, VPN/SSH path, and VNC switch. |
| Authentication fails | Account or viewer credentials | Use the configured user; do not disable authentication to make a test pass. |
| VNC connects but screen is black | Graphical session or display | Confirm Desktop is installed, a session is active, and the display is available to the compositor. |
| SSH works but VNC does not | Different services | SSH proves network access, not that a desktop or VNC server is running. |
| Viewer works on LAN but not from outside | Remote path | Check the VPN or SSH tunnel; do not open port 5900 publicly. |
Inspect the VNC listener and recent logs on the Pi:
If the listener is absent, use raspi-config to recheck VNC and log into the desktop. If the listener exists but the viewer shows a blank screen, check the graphical session and headless-display settings in the broader remote-desktop guide. Do not change several boot and display settings at once while diagnosing the first failure.
FAQ¶
Can I use VNC with Raspberry Pi OS Lite?¶
Not with Lite alone. It has no graphical desktop to share. SSH is the lighter option for administration.
Is VNC secure over the internet?¶
Use a private VPN or an SSH tunnel for remote access, and keep account authentication enabled. Avoid exposing the VNC service through a public router port forward.
Can Raspberry Pi Connect replace VNC?¶
For supported Wayland desktops, Connect offers browser-based screen sharing without finding the Pi's public address. It shares an existing graphical session; see the official Connect documentation for its requirements.