Apple OS X: Install X Window System XQuartz For SSH X11 Forwarding On a Mavericks or Yosemite

Posted on in Categories , , , , last updated May 5, 2015

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 [email protected] and ssh -Y [email protected] commands on both OS X Mountain Lion and Apple OS X Mavericks/Yosemite. But, I am unable to use the ssh command with X11.

How do I fix this problem on OS X and enable X11 forwarding with ssh command? How do I install XQuartz ( server on Apple OS X Mountain Lion or Mavericks or Yosemite?

You need to install XQuartz ( on 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 OS X. This is Apple’s version of the X server.

The latest version of Apple OS X Mountain Lion and Mavericks no longer ships with 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 XQuartz server

Visit this page and download XQuarz server. 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:

Step #2: ssh X11 forwarding syntax

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 &


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


In this example, login to the Linux based nas01 server as a user called nixcraft:
$ ssh -X [email protected]
$ 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: ( XQuartz ) loaded at the Dock
Fig.01: ( 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
See also
  • Man pages: ssh_config(5),sshd(8),ssh(1)

Posted by: Vivek Gite

The author is the creator of nixCraft and a seasoned sysadmin and a trainer for the Linux operating system/Unix shell scripting. He has worked with global clients and in various industries, including IT, education, defense and space research, and the nonprofit sector. Follow him on Twitter, Facebook, Google+.

12 comment

  1. 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?

  2. 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

  3. @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.

  4. 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.”

  5. 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 Comment