X11 Forwarding not working: step-by-step setup in Linux

Why X11 Forwarding is Not Working?

X11 Forwarding is an SSH mechanism that allows you to run graphical applications on a remote Linux server, displaying their windows on your local computer. Issues with its operation usually arise due to:

• Disabled option in the SSH daemon configuration (sshd_config).
• Absence of the xauth package on the server, which manages X authorization.
• Conflict with the modern display system Wayland on the client (especially in Ubuntu 22.04+ and Fedora).
• Incorrect use of the -X (untrusted) and -Y (trusted) flags when connecting.
• Network access issues or the DISPLAY environment variable.

This guide will help you systematically diagnose and fix the problem on both the server and client sides.

Step 1: Check the Local SSH Client

Before changing server settings, ensure that your local SSH client allows X11 Forwarding.

1. Open a terminal on your computer (Linux/macOS) or PowerShell/WSL on Windows.
2. Check the main client config:

   grep -i forwardx11 /etc/ssh/ssh_config
   

   There should be a line ForwardX11 yes or ForwardX11Trusted yes. If the line is missing or set to no, add it to the end of the file (sudo privileges required) or create/update your personal config ~/.ssh/config:

   Host *
       ForwardX11 yes
       ForwardX11Trusted yes
   

   💡 Tip: Using ForwardX11Trusted yes (equivalent to the flag ssh -Y) resolves most issues with access rights to the X server, but has lower security isolation. This is acceptable for trusted internal networks.

Step 2: Configure the SSH Daemon on the Server (sshd_config)

On the remote server, ensure that the sshd daemon is configured to accept X11 requests.

1. Connect to the server in the usual way (without -X):

   ssh user@your_server
   

2. Edit the configuration file sshd_config (usually /etc/ssh/sshd_config):

   sudo nano /etc/ssh/sshd_config
   

3. Find and uncomment (remove #) or add the following lines:

   X11Forwarding yes
   X11DisplayOffset 10
   X11UseLocalhost yes
   

   • X11Forwarding yes — enables the mechanism.
   • X11DisplayOffset 10 — standard offset for display numbers.
   • X11UseLocalhost yes — binds forwarding to localhost (safer).
4. Important: Ensure that there is no line X11Forwarding no in the same file or that it does not override ours.
5. Save the file and restart the SSH service:

   # For systemd (most modern distributions)
   sudo systemctl restart sshd
   
   # Or for older systems (SysVinit)
   sudo service ssh restart
   

Step 3: Install and Check the xauth Package

The xauth package is critically important. It stores and manages "cookies" (tokens) for authenticating X clients.

1. Check if it is installed:

   which xauth
   

   If the command returns nothing or xauth not found, install it:

   # For Debian/Ubuntu
   sudo apt update && sudo apt install xauth
   
   # For RHEL/CentOS 8+ / Rocky / AlmaLinux
   sudo dnf install xauth
   
   # For CentOS 7 / RHEL 7
   sudo yum install xauth
   

2. After installation, reconnect to the server with the -Y flag (trusted forwarding):

   ssh -Y user@your_server
   

Step 4: Diagnostics After Connecting

After connecting with the -Y flag, run a few commands on the server to check the status.

1. Check the DISPLAY variable:

   echo $DISPLAY
   

   Expected result: localhost:10.0 (or localhost:11.0, etc.). If the output is empty or contains :0 — forwarding did not activate.
2. Check the xauth token:

   xauth list
   

   The output should contain an entry for the display indicated in $DISPLAY (e.g., hostname/unix:10). If the list is empty — there is a problem with cookie generation.
3. View connection logs: On the client, when connecting, you can add verbose output flags:

   ssh -Yv user@your_server
   

   Look for lines in the output like X11 forwarding request accepted and Allocated X11 display. On the server, check the sshd logs:

   sudo journalctl -u sshd -f
   

   (in a separate terminal while you try to connect). Look for errors like X11 connection refused or xauth: unable to open display.

Step 5: Troubleshooting Wayland Issues on the Client

If your local computer (especially Ubuntu 22.04, Fedora 36+) uses Wayland instead of Xorg by default, classic X11 Forwarding may not work.

1. Temporary solution: On the login screen (GDM/LightDM), before entering your password, select the "Ubuntu on Xorg" session (or similar) instead of "Ubuntu on Wayland". After that, log back in and try connecting again.
2. Permanent solution (if possible): Disable Wayland in the GDM config by editing /etc/gdm3/custom.conf (for Ubuntu) or /etc/gdm/custom.conf:

   #WaylandEnable=false
   

   (uncomment the line). Then reboot the system.
3. Alternative for Wayland: Use xwayland — a compatibility layer that is usually installed by default. Ensure it is working: echo $XDG_SESSION_TYPE should output x11 after switching to an Xorg session. For pure Wayland without switching sessions, X11 Forwarding will not work.

Step 6: Alternative Options (if nothing helps)

If the settings are correct but applications still do not start, try:

• Use ssh -X instead of -Y (and vice versa). Some applications (e.g., sudo gedit) require -Y for a trusted channel.
• Run applications with kernel access disabled: xhost +SI:localuser:root (on the local machine, unsafe!) or use sudo -E on the server to pass the DISPLAY variable.
• Set up a tunnel manually: As a last resort, you can manually forward the X11 server port (usually 6000+display), but this is more complicated and less secure.
• Use VNC or RDP: If X11 Forwarding is unstable, set up a VNC server (e.g., TigerVNC) or an RDP server (xrdp) on the remote machine. This will transmit the entire desktop but will require additional resources and a separate client.

⚠️ Important: Never use xhost + (allow everyone) on a working machine. This is a serious security vulnerability that allows any local application to intercept input and screen.

Frequently Asked Questions

Can X11 Forwarding be used through Windows? Yes, but you need an X server for Windows, such as VcXsrv or Xming. Install it, run it, allowing "Disable access control". Then in WSL2 or PuTTY, configure X11 Forwarding. In PuTTY, this is an option under Connection -> SSH -> X11.

What to do if you get the error Can't open display? This is a classic error. Check in order: 1) the DISPLAY variable is set (echo $DISPLAY), 2) the xauth package is installed, 3) X11Forwarding yes is set in sshd_config, 4) you connected with the -X or -Y flag, 5) the local X server (on your PC) is running (on Linux it is usually there, on Windows — VcXsrv).

Why does ssh -X work while ssh -Y does not (or vice versa)? The -X flag enables untrusted forwarding with restrictions (e.g., prohibiting connections to the X server from root). The -Y flag is trusted, with no such restrictions. If an application requires root rights or extended X capabilities, it may only work with -Y. If there is a malicious process on the server, -Y is potentially more dangerous.

How to disable X11 Forwarding if it is enabled by default? In ~/.ssh/config, add for a specific host:

Host problematic-server
    ForwardX11 no

Or use the flag when starting: ssh -x user@server (lowercase x).

Conclusion

Setting up X11 Forwarding is a chain of several components: correct sshd configuration on the server, presence of xauth, proper flags when connecting, and compatibility of the client environment (Xorg vs Wayland). By following this guide step by step, you can diagnose and resolve most common failures. If the problem persists, check network policies (firewall) and ensure there are no restrictions on the server through Match blocks in sshd_config.