I need to tunnel X Window securely over SSH bases session so that I run X program on my remote Linux/Unix server/workstation and get back display to my Apple Macbook pro laptop. I tried the ssh -X user@server1 and ssh -Y user@server2 commands on macOS. However, I am unable to use the ssh command with X11 forwarding. How do I get X11 forwarding in macOS to run graphical apps remotely from a Linux server? How can I fix this problem on OS X and enable X11 forwarding with ssh command? Can you explain how to install X Window XQuartz server on Apple OS X Mountain Lion or Mavericks or Yosemite or macOS?

Tutorial details
Difficulty level Intermediate
Root privileges Yes
Requirements XQuartz and macOS with terminal
Est. reading time 6 mintues
You need to install X Window XQuartz (X11.app) on macOS or OS X v10.8 or above to use ssh with x11 forwarding. The XQuartzproject is an open-source effort to develop a version of the X.Org X Window System that runs on macOS and OS X. This is Apple’s version of the X server. The latest version of macOS or Apple OS X Mountain Lion and Mavericks no longer ships with X11.app i.e. XQuartz server. You need to download and install the server before using ssh with X11 forwarding.

Can’t load X11 after OS X Yosemite upgrade

You need to delete / remove existing XQuartz server and reinstall it again.

Step 1 – Download and install X Window XQuartz on macOS

Visit this page and download XQuarz server for macOS. Once downloaded the XQuarz package, install the server by double clicking the package icon in your Downloads folder. Please follow the instructions on-screen to complete the installations:

Installing X Window XQuartz on macOS using brew command

Another option is to install Homebrew on macOS to use the brew package manager as follows using the Termaial app:
brew install --cask xquartz

How do I run graphical programs remotely from a Linux server

Want to run graphical programs remotely from a Linux server? You need XQuartz on your Mac and can be installed using the brew

Step 2 – Reboot your Mac

You need to reboot the Mac to work it correctly. Otherwise, you will get various warnings or errors. Click on the Apple icon and then Restart. Another option is to type the following command using Termaial app:
sudo reboot

Step 3 – ssh X11 forwarding syntax for macOS

A tunneling protocol is a network protocol which encapsulates a payload protocol, acting as a payload protocol. Reasons to tunnel include carrying a payload over an incompatible delivery network, or to provide a secure path through an untrusted network. SSH is frequently used to tunnel insecure traffic over the Internet in a secure way. Simply type the following command to use X over ssh:

ssh -X user@RemoteserverNameHere
x-app-name-here &

OR

ssh -X userName@Server-Ip-Address-Here
x-window-app-name-here &

Step 4 – Enables and use trusted X11 forwarding

A small number of X11 GUI apps may require the use of -Y option instead of -X.

The syntax is:

ssh -Y user@server-ip
app-name &

Trusted X11 forwardings are not subjected to the X11 SECURITY extension controls. From the ssh man page:

X11 forwarding should be enabled with caution. Users with the ability to bypass file permissions on the remote host (for the user’s X authorization database) can access the local X11 display through the forwarded connection. An attacker may then be able to perform activities such as keystroke monitoring. For this reason, X11 forwarding is subjected to X11 SECURITY extension restrictions by default. Please refer to the ssh -Y option and the ForwardX11Trusted directive in ssh_config(5) for more information.

Step 5 – Run graphical programs remotely from a Linux or BSD server on macOS

The main advantage of using xterm instead of the built-in Terminal app is that xterm works without rebooting your Mac.

XQuartz.app itself comes with xterm (Terminal). You can use that app too apart from built-in Terminal app. To run X11 Forwarding on Mac:

  1. Run XQuartz.app Applications.
  2. Then right click on the XQuartz icon in the dock and select Applications > Terminal:
    X11 Forwarding on MacOS using Xterm app and ssh
  3. You should see a new xterm terminal windows
  4. Finally, use the xterm app and ssh into the Linux or BSD server:
    ssh -X UserName@your-server-ip-here
    OR
    ssh -Y UserName@home-wan-linux.cyberciti.biz
  5. Then type app name such as:
    xeyes
    How To Set Up And Use X11 Forwarding On Linux And MacOS

Examples

In this example, I am going login to the Linux based nas01 server as a user called nixcraft using macOS Terminal app itself:
$ ssh -X nixcraft@nas01
OR
$ ssh -X nas01
You will see XQuartz server in the Dock i.e. a new XQuartz icon sits at the bottom of side of your screen as follows:

Fig.01: X11.app ( XQuartz ) loaded at the Dock

Fig.01: X11.app ( XQuartz ) loaded at the Dock

To test X11 by running xeyes or xclock or any another GUI application you wish. The syntax is as follows on your remote server:
$ app-name
$ /path/to/app-name
$ app-name &

In this example, I am running xeyes on remote server:
$ xeyes
Sample outputs:
Animated gif 01: X11 Forwarding on OS X v10.8+. This demo was tested on OS X 10.9 i.e. Mavericks and Linux remote server.

Animated gif 01: X11 Forwarding on OS X v10.8+. This demo was tested on OS X 10.9 i.e. Mavericks and Linux remote server.

Edit your ~/.ssh/config file and append the following line and you wouldn’t need pass the -X option to ssh command:

ForwardX11 yes

Finally, you can run ssh in the background after running a GUI app as follows:

ssh user@server -f -X app-Name
ssh nixcraft@nas01 -f -X gpass
ssh nixcraft@nas01 -f -X xeyes

Troubleshooting

Is X11 forwarding still not working on your Mac? Try these tips on your Linux or BSD/Unix server:

  1. Make sure xauth is installed on your Linux/BSD server. Use the type command/command command:
    type -a xauth
    command -V xauth
  2. After login using ssh client, you must see the DISPLAY variable set by ssh client. Without this variable X11 forwarding will never work. For instance:
    echo "$DISPLAY"
  3. Finally, run the following command and make sure X11 forwarding is enabled on your SSHD server:
    sudo sshd -T | grep -i X11
  4. If not enabled edit the /etc/ssh/sshd_config and set those option:
    sudo vim /etc/ssh/sshd_config
    Append the following settings:
    x11forwarding yes
  5. It would be best if you reloaded sshd server as per your OS. For example:# Debian/Ubuntu Linux server #
    sudo systemctl restart ssh.service
    # RHEL/CentOS Linux user run: #
    sudo systemctl restart sshd.service
Troublshooting X11 Forwarding on Linux and BSD Unix servers

Troubleshooting ssh X11 Forwarding issues on Linux and BSD Unix servers

Summing up

You learned how to install X Window XQuartz on macOS to enable and use X forwarding with ssh command. See the following man pages:
man ssh
man sshd
man sshd_config
man ssh_config


🐧 Get the latest tutorials on Linux, Open Source & DevOps via RSS feed or Weekly email newsletter.

🐧 12 comments so far... add one

CategoryList of Unix and Linux commands
Disk space analyzersdf ncdu pydf
File Managementcat tree
FirewallAlpine Awall CentOS 8 OpenSUSE RHEL 8 Ubuntu 16.04 Ubuntu 18.04 Ubuntu 20.04
Network UtilitiesNetHogs dig host ip nmap
OpenVPNCentOS 7 CentOS 8 Debian 10 Debian 8/9 Ubuntu 18.04 Ubuntu 20.04
Package Managerapk apt
Processes Managementbg chroot cron disown fg jobs killall kill pidof pstree pwdx time
Searchinggrep whereis which
User Informationgroups id lastcomm last lid/libuser-lid logname members users whoami who w
WireGuard VPNAlpine CentOS 8 Debian 10 Firewall Ubuntu 20.04
12 comments… add one
  • Debjit Saha Jan 13, 2014 @ 2:25

    How can I start other apps such as Firefox or XCode. One running them using open command, these apps are opening in the remote mac system not in my ssh terminal

  • Tom Cox Mar 4, 2014 @ 23:50

    When you say this:

    To test X11 by running xeyes or xclock or any another GUI application you wish. The
    syntax is as follows on your remote server:
    $ app-name
    $ /path/to/app-name
    $ app-name &

    are these three alternatives?

    • GTFO Mar 21, 2014 @ 8:22

      Yup. If xclock is in PATH, you can type the following on remote host:

      xeyes

      If xeyes is not in the PATH, type full path such as:

      /usr/local/bin/xeyes
  • sunny Mar 5, 2014 @ 4:32

    How can I start other apps such as Firefox or XCode. One running them using open command, these apps are opening in the remote mac system not in my ssh terminal

  • Nico van der Linden Mar 5, 2014 @ 10:00

    Do anyone know if you can use XQuartz on a DIFFERENT user as which you logged on to the SSH session? I work for some customers where you must logon with a network account and a token to the linux environment and from there you can su into other users.

    The X-forward runs fine for the user I used to logon but when I su in a different user it does not accept it anymore. On windows I always used Exceed and there you had to set a “DISPLAY” variable under the account you used to run the X application. So if that can be used with XQuartz then it would be fine as well.

    Kind Regards,
    Nico van der Linden

    • GTFO Mar 21, 2014 @ 8:26

      Use sux command – a wrapper around su which will transfer your X credentials to the target user. If sux is not installed try xauth command.

  • Trane Francks Sep 27, 2014 @ 6:13

    @sunny: “How can I start other apps such as Firefox or XCode. One running them using open command, these apps are opening in the remote mac system not in my ssh terminal”

    X forwarding only works for X Windows System-based applications. To do remote work on an OS X system, it’s generally better to use Apple Remote Desktop. With Remote Desktop, you log into the remote GUI and do all your work remotely rather than pulling the app and visualizing it on your own desktop with your X server.

  • Florian Beer May 5, 2015 @ 8:04

    To display the whole desktop of a remote X-Window system you can use “Xnest”.
    There is a post on my blog, but it’s in German. Maybe Google Translate can help if you can’t make sense of it, but it’s a pretty straight forward process.

    http://blog.no-panic.at/2005/04/05/xnest-unter-os-x/

  • s&p Jan 20, 2016 @ 3:42

    Thank you!

  • jax Apr 22, 2016 @ 22:21

    This doesn’t work on El Capitan which fails on ssh -X with the message “Warning: untrusted X11 forwarding setup failed: xauth key data not generated
    Warning: No xauth data; using fake authentication data for X11 forwarding.”

  • jax Apr 22, 2016 @ 22:27

    Hmmm … I sorta take my previous comment back …. ssh issues the failure message above … then X forwarding works anyway. Go figure.

  • Allan Mar 3, 2017 @ 19:12

    I have a remote CentOS server that I can login to using the Terminal app with ssh and a public/private key exchange. After invoking ssh, I get a request back for the passphrase for the identity file at ~.ssh/id_dsa. This works just fine in Terminal but consistently fails in XQuartz for no apparent reason. Because of the complexity of the passphrase, I’d normally just copy it from another location and then paste it into the response and hit Enter.

    Any idea why that fails off the bat in an XQuartz window and yet works in Terminal?

Leave a Reply

Your email address will not be published.

Use HTML <pre>...</pre> for code samples. Still have questions? Post it on our forum