SSH X11 forwarding: -X vs -Y, xauth and XQuartz

Set up the server

Install xauth, plus a small program to test with:

sudo apt install xauth x11-apps

In /etc/ssh/sshd_config, set:

X11Forwarding yes

The OpenSSH default is no, although the configuration file on Debian sets it to yes. Reload after a change:

sudo sshd -t && sudo systemctl reload ssh

The service is called sshd on some systems.

Connect and test

ssh -X user@server
echo $DISPLAY
xeyes

DISPLAY should look like localhost:10.0. That is the proxy that sshd creates on the server, not your real display. Do not set DISPLAY by hand.

To make it permanent for one server, use ~/.ssh/config:

Host server
  ForwardX11 yes

-X or -Y

	`-X`, untrusted	`-Y`, trusted
Access to your display	Limited by the X11 SECURITY extension	Full
Screenshot of the whole display with `xwd -root`	Failed: `unable to get image`	Worked
Other window's properties with `xprop`	Worked	Worked
Time limit	New windows refused after 20 minutes	None

Untrusted is the upstream default for -X. These results come from our test on Xvfb with X authentication on. Without authentication, -X limited nothing. So -X reduces what a program can reach, but it does not isolate it. Some programs lose features in this mode: xeyes printed extension "XInputExtension" missing and still opened.

If windows stop opening after 20 minutes under -X, with Can't open display, raise the limit in ~/.ssh/config, for example ForwardX11Timeout 8h.

On Debian and Ubuntu, -X behaves like -Y

Debian's client sets ForwardX11Trusted yes by default, so -X is trusted there. In our test ssh -G showed yes on Debian 13 and no on macOS. For the stricter mode on Debian, add -o ForwardX11Trusted=no, which is how we ran the untrusted test. See what your client does with:

ssh -G server | grep -i forwardx11

The security risk

With trusted forwarding, a program on the server can capture your screen and read keys you type in other windows. So can anyone who can get past file permissions on the server, such as root, because they can reach the same forwarded display. Do not forward X11 to a server you do not trust. Use -Y only when a program fails with -X.

Forwarding your SSH agent carries a similar risk for your keys: see SSH agent forwarding risks.

On a Mac: XQuartz

macOS has no X server. Install XQuartz, then log out and back in so that DISPLAY gets set in your session. On Debian we confirmed what happens with an empty DISPLAY: if echo $DISPLAY is empty, ssh -X connects without forwarding and without any visible error. Only ssh -v tells you X11 forwarding requested but DISPLAY not set.

The macOS client looks for xauth at /usr/X11R6/bin/xauth by default. If it complains, point it at the one from XQuartz, which normally installs under /opt/X11, in ~/.ssh/config:

Host *
  XAuthLocation /opt/X11/bin/xauth

Errors

Message	Cause	Check
`X11 forwarding request failed on channel 0`	`X11Forwarding no` on the server, or no `xauth` there. We got this for both	`sudo sshd -T \| grep -i x11forwarding` and `which xauth`
`Error: Can't open display:` with nothing after it	`DISPLAY` is empty, so forwarding is off	`echo $DISPLAY` on both sides, and `ssh -v`
`Warning: untrusted X11 forwarding setup failed: xauth key data not generated`	No `xauth` on your machine	`which xauth`, then set `XAuthLocation`

Questions

What is the difference between ssh -X and ssh -Y?

-X is untrusted forwarding, limited by the X11 SECURITY extension. -Y is trusted and gives the program full access to your display. On Debian and Ubuntu, -X is trusted by default.

Why does ssh -X connect but no window opens?

Forwarding did not start. Either DISPLAY is empty on your machine, or the server has X11Forwarding no or no xauth. ssh -v shows which.

Do I need XQuartz on a Mac?

Yes. macOS has no X server. Install XQuartz, then log out and back in before you use ssh -X.

Does X11 forwarding work on Wayland?

Yes, through XWayland, which most Wayland desktops run. If echo $DISPLAY shows a value such as :0 on your machine, ssh -X works as usual and the programs open as X11 windows.

Why is X11 forwarding so slow?

X11 makes many round trips between the program and your screen, so network latency matters more than bandwidth. ssh -C compresses the traffic, which helps on slow links. For a whole desktop over the internet, VNC or RDP through an SSH tunnel is usually smoother.

Sources

More in Sessions and tmux

All guides