A GUI program over SSH says it cannot open the display
Gtk-WARNING **: cannot open display: localhost:10.0Short answer
ssh must forward X11 and the remote sshd must allow it. Connect with ssh -X, confirm sshd_config on the server has X11Forwarding yes, and make sure nothing in your shell startup files overwrites DISPLAY. ssh sets DISPLAY itself, and a hand-set value breaks the forwarded one.
Fix it fast
1Find out which cause you have
Log in again with X11 forwarding asked for and verbose output on, then print DISPLAY on the remote side. A forwarded session shows a value with a display number above zero, such as localhost:10.0.
ssh -v -X user@remote-host echo $DISPLAY2Match what you see, then jump to its fix
- 1
echo $DISPLAY prints an empty line on the remote host.The client did not ask for X11 forwardingFix - 2
ssh -v shows the request being made, yet DISPLAY stays empty on the remote host.The server's sshd does not allow X11 forwardingFix - 3
ssh -v shows forwarding set up, but DISPLAY holds a different value, such as :0, once the shell is ready.A startup file overwrites DISPLAYFix
- 1
What does the error look like?
Gtk-WARNING **: cannot open display: localhost:10.0cannot open display:
Cause 1 of 3
The client did not ask for X11 forwarding
1Check
ForwardX11 defaults to no, so a plain ssh login forwards nothing. Check whether you used -X (or -Y) and whether your ssh config sets ForwardX11 for that host.
grep -n -i forwardx11 ~/.ssh/config2Fix
Connect with -X, or set it for the host in your ssh config. Use -Y only if a program fails under the default untrusted mode.
ssh -X user@remote-host
# ~/.ssh/config
Host remote-host
ForwardX11 yes3Verify
DISPLAY is now set in the remote shell.
echo $DISPLAYConfirmed by man.openbsd.org
Cause 2 of 3
The server's sshd does not allow X11 forwarding
1Check
X11Forwarding in sshd_config defaults to no. Look at the server's config and any files it includes.
sudo grep -ri x11forwarding /etc/ssh/2Fix
Set X11Forwarding to yes on the server and restart sshd. Leave X11UseLocalhost at its default of yes unless you know you need the wildcard address.
# /etc/ssh/sshd_config
X11Forwarding yes
sudo systemctl restart sshd3Verify
Log out, log in again with ssh -X and print DISPLAY.
ssh -X user@remote-host
echo $DISPLAYConfirmed by man.openbsd.org
Cause 3 of 3
A startup file overwrites DISPLAY
1Check
The ssh manual says the user should not set DISPLAY by hand, because ssh points it at a proxy X server on the remote host. Search your startup files for an export.
grep -n DISPLAY ~/.bashrc ~/.profile ~/.bash_profile ~/.zshrc 2>/dev/null2Fix
Remove the line that exports DISPLAY from the remote account's startup files, then log in again so ssh sets it.
# delete or comment out lines such as:
# export DISPLAY=:03Verify
After a fresh login with -X, DISPLAY shows localhost and a number above zero.
ssh -X user@remote-host 'echo $DISPLAY'Confirmed by man.openbsd.org
How do I stop it coming back?
- Use ssh -X only for the machines that need GUI tools, and prefer a plain terminal workflow elsewhere.
- Never export DISPLAY in startup files of an account you reach over ssh.
- Keep sshd_config under change control so X11Forwarding does not flip back after an upgrade.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Security
SSH refuses your key and ends with Permission denied (publickey)
user@203.0.113.10: Permission denied (publickey,password).
The server accepted the connection but found no key it would take.
5 causes, each with a fixSecurity
AuthenticationException: your certificate validation callback returned false
System.Security.Authentication.AuthenticationException
This message means a validation callback was installed, yours or one a library added, and it returned false.
3 causes, each with a fixSecurity
SSH to an EC2 instance fails with Permission denied (publickey,gssapi-keyex,gssapi-with-mic)
ec2-user@ec2-203-0-113-25.compute-1.amazonaws.com: Permission denied (publickey).
On EC2 this error almost always means the instance did not accept your key for that user.
3 causes, each with a fixSecurity
gcloud init cannot finish the sign-in step
Enter authorization code
gcloud init signs in through a browser.
3 causes, each with a fixSecurity
A GitHub Actions SSH deploy step cannot log in to the server
ssh: handshake failed: ssh: unable to authenticate
The runner reached your server but the server refused the login.
4 causes, each with a fixSecurity
SSH to GitHub asks to confirm the host, or hangs on that prompt
ED25519 key fingerprint is SHA256:
SSH has never seen github.com from this machine, so it asks you to trust the server key.
2 causes, each with a fix