See all macOS (formerly Mac OS X or OS X) Unix related Howtos/Tutorials
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 macOS terminal
Category Terminal/ssh
Prerequisites Intel or Apple Silicon Mac
OS compatibility macOS Unix
Est. reading time 6 minutes
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. Also, native Apple Silicon support is added so you can use with M1 CPU.

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 the brew command

Another option is to install Homebrew on macOS to use the brew package manager as follows using the Terminal 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 reboot command using the Terminal 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 ssh command to use X over ssh based session. For example:
$ 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’. For example:$ 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
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 using the help or man command:
$ man ssh
$ man sshd
$ man sshd_config

See also

$ man ssh_config

🥺 Was this helpful? Please add a comment to show your appreciation or feedback.

nixCrat Tux Pixel Penguin
Hi! 🤠
I'm Vivek Gite, and I write about Linux, macOS, Unix, IT, programming, infosec, and open source. Subscribe to my RSS feed or email newsletter for updates.

22 comments… add one
  • Anne Holmes Apr 24, 2022 @ 1:43

    I was installing XQuartz on Apple Mac with native Apple silicon support. I thought it wouldn’t work, but it worked flawlessly.

  • Shashi Sep 6, 2022 @ 5:45

    Thanks. It was helpful. :)

  • Anonymous Nov 3, 2022 @ 11:13

    Great guide, thank you!

    Any idea how to get fonts to display properly, though? Mine look very blurry / low res.

    Thanks

    • 🛡️ Vivek Gite (Author and Admin) Vivek Gite Nov 5, 2022 @ 18:55

      That has been a problem for some time. But unfortunately, I need to figure out how to fix it.

  • Vadim Nov 8, 2022 @ 13:19

    Hi, when I try to run a program via ssh there’s an error appears:
    “X11 connection rejected because of wrong authentication.”
    Any ideas of how can it be fixed?
    Thank you.

  • Nick Feb 8, 2023 @ 19:54

    Is there a way to display the entire desktop as one window so that apps do not support X can be viewed when launched in the GUI?

    • 🛡️ Vivek Gite (Author and Admin) Vivek Gite Feb 8, 2023 @ 21:12

      It is possible but it will be slow. It is better to install VNC Service on Linux and VNC client on macOS/OS X and then connect it via ssh to load the entire desktop.

  • Thomas S Jun 25, 2023 @ 14:09

    I’m glad this post popped up again! It is just what I needed to access Crashplan running on a Linux box from my Mac. Crashplan gui app is so annoying it actually does not even run on localhost using the XFCE desktop on Debian 12. I tried to figure out why, but failed.

    Years ago I had tried Quartz X11 on Mac and didn’t have much success, but surprisingly on an M1 Mac running Ventura it works perfectly for this purpose! I’m one of your Patreon subscribers. Thank you!

    • 🛡️ Vivek Gite (Author and Admin) Vivek Gite Jun 25, 2023 @ 15:23

      Happy to help, and thank you for being a Patreon subscriber.

Leave a Reply

Your email address will not be published. Required fields are marked *

Use HTML <pre>...</pre> for code samples. Your comment will appear only after approval by the site admin.