These notes cover Raspberry Pi OS Bookworm with an existing graphical desktop on a trusted LAN. They explain the Wayland routes and service checks. Do not forward the VNC port from an internet router to the Pi.
What are you setting up?
The Pi runs the VNC server; the viewer runs on your other machine. Begin with an existing graphical desktop on the Pi and both devices on the same trusted LAN.
Confirm the Pi’s hostname with hostname and its addresses with hostname -I. Debian Bookworm hostname(1) documents -I.
Which Bookworm desktop do these notes cover?
Use these menu notes only for an existing Wayland desktop using wayfire or labwc. In Bookworm raspi-config, choose Interface Options → VNC, then Yes and Finish. The Wayland branch enables wayvnc.service. On the non-Wayland branch, the toggle installs realvnc-vnc-server and enables vncserver-x11-serviced.service. The checks below apply only to the Wayland route. Source: Raspberry Pi raspi-config, Bookworm branch, is_wayland() and do_vnc().
Enable VNC on Raspberry Pi OS
Run sudo raspi-config, then choose Interface Options, then VNC. On a Wayland desktop, raspi-config’s VNC option enables the built-in wayvnc server; its configuration is in /etc/wayvnc/. Use the network restriction guidance with the port your server actually uses.
$ systemctl status wayvnc $ sudo ss -tlnp | grep 5900
Check for an active service and a listener on TCP 5900. If wayvnc is inactive, inspect journalctl -u wayvnc and journalctl -b | grep -i wayvnc. These are service checks; a visible desktop still needs to be checked in the viewer. Source: Raspberry Pi wayvnc 0.8.0-rel-1 source package, pios-control/usr/lib/systemd/system/wayvnc.service and wayvnc.scd.
Which viewer address applies?
On a Debian Bookworm client, the named viewer package is tigervnc-viewer, version 1.12.0+dfsg-8. Its literal-port form uses two colons: 192.168.1.42::5900, with the Pi’s numeric address replacing the example address. In Raspberry Pi’s wayvnc 0.8.0-rel-1 package, PAM authentication uses the Pi’s Linux user name and password; see the Raspberry Pi wayvnc 0.8.0-rel-1 source package, pios-control/etc/wayvnc/config and wayvnc.pam. These are address and credential notes. Do not dismiss a certificate or identity warning automatically.
Use the Pi’s address from hostname -I in place of 192.168.1.42. A refused connection can mean that no process is listening on the requested port; IETF RFC 9293, section 3.5.2 describes the reset response for a closed connection (published August 2022).
For a blank display, see the black-screen troubleshooting article.
X11 session
TigerVNC is suited to a separate virtual X desktop. See Debian Bookworm tigervncserver(1) for the version-specific reference.
How should you limit access?
Keep access on a trusted LAN, a VPN, or an authenticated tunnel. For remote-access procedures, see the SSH tunnel guide.
Restrict VNC to your network
Keep VNC on your trusted LAN, VPN or authenticated tunnel. For a host already using UFW, this example allows TCP 5901 (display :1 at its default port) from your LAN subnet. Replace 192.168.1.0/24 with your actual subnet, and confirm the server’s configured port before using it.
- Add the LAN allow rule:
sudo ufw allow from 192.168.1.0/24 to any port 5901 proto tcp - After the allow rule, add the deny rule for TCP 5900–5910 from anywhere:
sudo ufw deny proto tcp from any to any port 5900:5910 - Inspect the rules:
sudo ufw status numbered
Have the administrator review existing rules and verify access from both an intended client and outside the allowed subnet. Never forward TCP 5900 from an internet router to the Pi. For a Pi listening on 5900, use the range alternative below only if both ports should be allowed; this display :1 example does not enable access to 5900.
Test this on your own host before relying on it.
If you need both ports
Replace the single-port allow step above with sudo ufw allow from 192.168.1.0/24 to any port 5900:5901 proto tcp. Replace the subnet with your actual LAN subnet. Then follow the deny and inspection steps above. Use this alternative only when you intend to allow both TCP 5900 and 5901.
Test this on your own host before relying on it.
Change any default or reused password. Prefer a long unique passphrase, keep Raspberry Pi OS patched, and disable accounts you no longer use. Limit SSH with keys and firewall rules. Check listeners periodically with sudo ss -tlnp; each exposed service should have a reason to exist. If guests share the LAN, use network segmentation instead of treating Wi-Fi membership as authorization.
How do you choose a server?
Choose by the desktop you need to reach: the Wayland route described above, a separate virtual X desktop with TigerVNC, or an existing X11 display with x11vnc. The X11 section explains that session distinction. See the vendor directory for software options.
Did this work? Share the OS point release, server, viewer, and outcome in the Using VNC Technology group.
Discuss this in the community
Black screen on headless Raspberry Pi 5 after upgrade, cursor only
Sources accurate as of 30 September 2026.
Open-source VNC suits personal projects and home labs. When your business depends on remote access, RealVNC Connect adds end-to-end encryption, centralised management and commercial support from the team that created VNC.