Raspberry Pi VNC: RealVNC and wayvnc Setup Guide for Bookworm

Raspberry Pi VNC setup on Bookworm requires choosing the right server for your session type. Bookworm Desktop defaults to the Wayland compositor, which RealVNC Server does not support in its current release. For Wayland sessions, wayvnc is the correct choice and installs from APT with no account required. For X11 mode or headless installs, RealVNC remains the option available through raspi-config. This guide covers all three approaches: RealVNC under X11, wayvnc for the Wayland default session, and TigerVNC for headless Lite installs.

Last tested: Raspberry Pi OS Bookworm Desktop 64-bit | May 2025 | Raspberry Pi 4 Model B (4GB) | RealVNC Server 7.x (X11 mode), wayvnc 0.8, TigerVNC 1.13, RealVNC Viewer 7.x

Raspberry Pi VNC Options on Bookworm

Three VNC server options cover the common Raspberry Pi VNC use cases on Bookworm. The right choice depends on whether the Pi runs the Desktop with Wayland, Desktop with X11, or Bookworm Lite with no GUI at all.

RealVNC Server is the historically standard choice and integrates with raspi-config. It requires X11 mode and a RealVNC account for cloud connections. Use it if you are running the Desktop in X11 mode and want the RealVNC Viewer app’s feature set including file transfer.

wayvnc is the correct choice for the default Bookworm Desktop Wayland session. It installs from APT, requires no account, and exposes the live desktop session over VNC on port 5900. Any standard VNC client connects to it.

TigerVNC creates virtual display sessions independent of any running desktop session. Use it on Bookworm Lite (no GUI installed) or when a headless virtual desktop is needed alongside the physical display. It installs from APT and requires no account.

Setting Up RealVNC on Raspberry Pi Desktop (X11 Mode)

If the Pi is running Bookworm Desktop and the goal is to use RealVNC Server, switch the display compositor to X11 first. Without this step, RealVNC cannot capture the Wayland session and connections fail silently.

Switch to X11 mode:

sudo raspi-config

Navigate to Advanced Options > Wayland and select X11. Reboot when prompted. After reboot, enable RealVNC Server:

sudo raspi-config

Navigate to Interface Options > VNC and select Yes. This installs and enables realvnc-vnc-server and starts it as a systemd service. Verify it is running:

systemctl status vncserver-x11-serviced

Expected result: The service shows active (running). The Pi’s IP address is now accessible via RealVNC Viewer on port 5900. If RealVNC Viewer shows “cannot currently show the desktop,” the Pi is still in Wayland mode. Confirm X11 is active with echo $XDG_SESSION_TYPE over SSH. It should return x11.

Download RealVNC Viewer on the connecting device from realvnc.com/en/connect/download/viewer. It is available for Windows, macOS, Linux, iOS, and Android. Open RealVNC Viewer, enter the Pi’s IP address or hostname in the address bar, and connect. For local network connections, no RealVNC account is required. Enter the Pi user’s credentials when prompted.

Set a VNC-specific password for the server if connecting without a RealVNC account:

vncpasswd -service

Expected result: RealVNC Viewer displays the Pi’s desktop at the configured resolution. Mouse and keyboard input controls the Pi in real time. If the connection is refused, check that port 5900 is not blocked: sudo ss -tlnp | grep 5900 should show the vncserver process listening.

Setting Up wayvnc for Wayland on Raspberry Pi

wayvnc is the correct VNC server for the default Bookworm Desktop Wayland session. It captures the live Wayland compositor output and serves it over VNC without requiring a compositor switch or account. Install it:

sudo apt update && sudo apt install -y wayvnc

wayvnc must be started from within a running Wayland session, not over SSH, because it attaches to the compositor socket. Log in to the Pi’s desktop locally or over a session that has access to the Wayland display, then run:

wayvnc 0.0.0.0 5900

To start wayvnc automatically when the Wayland session starts, add it to the autostart configuration. Create or edit ~/.config/wayvnc/config:

mkdir -p ~/.config/wayvnc
cat > ~/.config/wayvnc/config << 'EOF'
address=0.0.0.0
port=5900
enable_auth=true
username=youruser
password=changeme
EOF

Add wayvnc to the Wayland session autostart:

mkdir -p ~/.config/autostart
cat > ~/.config/autostart/wayvnc.desktop << 'EOF'
[Desktop Entry]
Type=Application
Name=wayvnc
Exec=wayvnc 0.0.0.0 5900
EOF

Expected result: Any VNC client (RealVNC Viewer, TigerVNC Viewer, Remmina) connecting to [pi-hostname]:5900 shows the live Wayland desktop. Mouse and keyboard input works in real time. If the connection is refused, confirm wayvnc is running with pgrep wayvnc and that the Wayland session is active. wayvnc exits if the Wayland session ends.

TigerVNC for Headless Raspberry Pi VNC

TigerVNC creates virtual display sessions independent of any physical display or running compositor. It is the right choice for Raspberry Pi OS Lite installs where no desktop is running, or for running a separate desktop environment over VNC without affecting the main display. Install TigerVNC and a lightweight desktop:

sudo apt update && sudo apt install -y tigervnc-standalone-server xfce4 xfce4-goodies dbus-x11

Set a VNC password:

vncpasswd

Create the startup script that TigerVNC runs when launching a session:

mkdir -p ~/.vnc
cat > ~/.vnc/xstartup << 'EOF'
#!/bin/bash
unset SESSION_MANAGER
unset DBUS_SESSION_BUS_ADDRESS
exec startxfce4
EOF
chmod +x ~/.vnc/xstartup

Start a VNC session on display :1 (port 5901):

vncserver :1 -geometry 1280x720 -depth 24

Expected result: Connecting to [pi-hostname]:5901 in a VNC viewer shows the XFCE desktop. The session is independent of any physical display. To kill the session: vncserver -kill :1. To start automatically on boot, create a systemd user service pointing to the vncserver :1 command. For monitoring the headless Pi's resources, see Raspberry Pi Power Monitoring via USB.

Connecting, Security, and Remote Access for Raspberry Pi VNC

On the local network, connect to the Pi by entering its hostname or IP address in the VNC viewer. Use [hostname]:5900 for RealVNC or wayvnc, and [hostname]:5901 for TigerVNC on display :1. Find the Pi's IP address with ip addr show eth0 or hostname -I over SSH, or from your router's DHCP client list.

VNC traffic is not encrypted by default. On a home LAN this is low risk, but if the VNC connection crosses any untrusted network segment it should be tunnelled over SSH. Set up an SSH tunnel on the connecting machine:

# On your local machine (Linux/macOS):
ssh -L 5900:localhost:5900 youruser@pi-hostname -N &

# Then connect VNC viewer to:
localhost:5900

On Windows, PuTTY handles the SSH tunnel: in the PuTTY session, navigate to Connection > SSH > Tunnels, add source port 5900, destination localhost:5900, and click Add before connecting.

For access from outside the home network without opening port 5900 on the router, Tailscale is the correct solution. Install Tailscale on both the Pi and the connecting device; both join the same Tailscale network and the Pi's Tailscale IP is accessible directly. VNC connects over the encrypted Tailscale tunnel without any port forwarding. For the full Tailscale setup, see Tailscale Raspberry Pi: Complete Secure Remote Access Guide. For classroom deployments where a teacher monitors multiple Pi desktops simultaneously, see Raspberry Pi in the Classroom: Setup, Projects, and Results.

Configure UFW to restrict VNC port access to the local subnet only:

sudo ufw allow from 192.168.1.0/24 to any port 5900
sudo ufw allow from 192.168.1.0/24 to any port 5901
sudo ufw limit ssh
sudo ufw enable

Expected result: VNC connections succeed from local network devices. External connections to ports 5900/5901 are blocked. SSH access is rate-limited but functional.

Troubleshooting Raspberry Pi VNC

"Cannot currently show the desktop" in RealVNC Viewer. The Pi is running in Wayland mode and RealVNC does not support Wayland. Switch to X11 in raspi-config (Advanced Options > Wayland > X11) and reboot. After rebooting, re-enable VNC in Interface Options. Confirm X11 is active with echo $XDG_SESSION_TYPE over SSH.

Connection refused on port 5900. Check that the VNC server is running: systemctl status vncserver-x11-serviced for RealVNC, pgrep wayvnc for wayvnc. If the service is not running, start it: sudo systemctl start vncserver-x11-serviced or run wayvnc 0.0.0.0 5900 from within the desktop session. Check UFW is not blocking the port with sudo ufw status.

Slow or laggy VNC performance. VNC performance depends heavily on network bandwidth and the resolution and colour depth of the session. Reduce the resolution in the VNC viewer's connection settings to 1280x720 or lower. Set colour depth to 16-bit instead of 24-bit. If using wayvnc, add -c tight compression option. Wired Ethernet always outperforms WiFi for VNC responsiveness.

wayvnc exits immediately after starting. wayvnc must be launched from within a running Wayland session with access to the compositor socket. Starting it over SSH without a Wayland environment fails because the WAYLAND_DISPLAY environment variable is not set. If launching over SSH is required, set the variable explicitly: WAYLAND_DISPLAY=wayland-1 wayvnc 0.0.0.0 5900. The display name may be wayland-0 or wayland-1; check with ls /run/user/1000/wayland-*.

Black screen in TigerVNC session. The xstartup script did not launch the desktop. Check ~/.vnc/*.log for error output. Common causes: XFCE not installed (run sudo apt install -y xfce4), missing dbus-x11, or the xstartup file does not have execute permission (chmod +x ~/.vnc/xstartup). Kill the session with vncserver -kill :1 and restart after fixing.

FAQ

Does Raspberry Pi VNC work with Wayland on Bookworm?

RealVNC Server does not work with the Wayland session on Bookworm in its current release. If Bookworm Desktop is in its default Wayland mode, use wayvnc instead. wayvnc installs from APT (sudo apt install wayvnc), runs natively in the Wayland session, and requires no RealVNC account. Any standard VNC client connects to it on port 5900. Alternatively, switch the Pi to X11 mode in raspi-config and use RealVNC as before.

How do I install RealVNC Viewer on a PC or Mac?

Download RealVNC Viewer directly from realvnc.com/en/connect/download/viewer. The realvnc-vnc-viewer APT package was removed from Raspberry Pi OS in 2023 and is no longer installable via apt install on Bookworm. RealVNC Viewer is available for Windows, macOS, Linux, iOS, and Android. For an alternative VNC client that does not require any account, TigerVNC Viewer or Remmina work with any of the three server setups in this guide.

Can I use Raspberry Pi VNC without a RealVNC account?

Yes, in two ways. First, direct connections to the Pi's IP address on port 5900 using RealVNC Viewer work without an account; authenticate with the Pi user's credentials or a VNC-specific password set with vncpasswd -service. Second, wayvnc and TigerVNC require no account at all and work with any VNC client. The RealVNC account is only required for cloud-based connections through RealVNC's relay infrastructure.

How do I access Raspberry Pi VNC from outside my home network?

Tailscale is the safest and simplest method. Install Tailscale on both the Pi and the remote device, join the same Tailscale network, and connect via VNC to the Pi's Tailscale IP address. No port forwarding is required and all traffic is encrypted. Alternatively, SSH tunnelling forwards port 5900 through an encrypted SSH connection: ssh -L 5900:localhost:5900 youruser@pi-hostname -N, then connect VNC to localhost:5900. Do not expose port 5900 directly to the internet without encryption.

What is the difference between RealVNC, wayvnc, and TigerVNC on Raspberry Pi?

RealVNC Server works with X11 sessions on Raspberry Pi Desktop, integrates with raspi-config, and offers cloud-based connections via a RealVNC account. wayvnc is Wayland-native and is the correct server for the default Bookworm Desktop session; it requires no account and works with any VNC client. TigerVNC creates virtual display sessions independent of the physical display, making it suitable for Bookworm Lite or headless setups. All three expose the desktop on port 5900 (5901 for TigerVNC display :1) and are accessed by standard VNC viewer software.

References:

• RealVNC Server documentation: help.realvnc.com
• wayvnc GitHub: github.com/any1/wayvnc
• TigerVNC documentation: tigervnc.org
• Raspberry Pi remote access documentation: raspberrypi.com/documentation/computers/remote-access
• Tailscale for Pi: tailscale.com/kb/1137/raspberry-pi

---

About the Author

Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.

Last tested hardware: Raspberry Pi 4 Model B (4GB). Last tested OS: Raspberry Pi OS Bookworm Desktop 64-bit. RealVNC Server 7.x (X11 mode), wayvnc 0.8, TigerVNC 1.13.