Running X11 applications over SSH

The program runs on the remote machine, but its windows open on your screen. Three things make that work: forwarding enabled on the server, an X server on your own machine, and the -X or -Y flag when you connect.

1Configure the server

On the machine you SSH into, edit /etc/ssh/sshd_config and make sure these lines are present and not commented out:

X11Forwarding yes
X11DisplayOffset 10
X11UseLocalhost yes

The server also needs xauth, which SSH uses to set up the authentication cookie:

sudo apt install xauth              # Debian/Ubuntu
sudo dnf install xorg-x11-xauth     # Fedora/RHEL

Then restart the SSH daemon:

sudo systemctl restart sshd   # or "ssh" on Debian/Ubuntu

2Run an X server locally

Pick your local operating system:

Nothing to install if you're in a desktop session. Both X11 and Wayland (through XWayland) work.

3Connect with forwarding

ssh -X user@host     # untrusted forwarding (more restricted)
ssh -Y user@host     # trusted forwarding (fewer issues, less secure)

To make it permanent for a host, add this to ~/.ssh/config:

Host myserver
    HostName host.example.com
    User user
    ForwardX11 yes
    ForwardX11Trusted yes

4Test it

echo $DISPLAY    # should show something like localhost:10.0
xclock           # or xeyes; install x11-apps if missing

If a clock window appears on your screen, forwarding works.

Troubleshooting

$DISPLAY is empty
The server isn’t forwarding. Recheck sshd_config, confirm xauth is installed, and connect with ssh -v -X to look for “X11 forwarding request failed.”
“cannot open display”
Your local X server probably isn’t running. This is common on macOS and Windows.
Apps crash with -X but work with -Y
Untrusted mode blocks some X extensions. Use -Y for hosts you trust.
Forwarding fails on servers with IPv4 disabled
Adding AddressFamily inet to sshd_config sometimes fixes it.

Performance

X11 forwarding can be sluggish for heavy GUI apps over slow links. Compression helps a little:

ssh -X -C user@host

For noticeably better responsiveness, use VNC, X2Go, or xpra instead.