Skip to Main Content

Running X Windows programs remotely


Working on a remote Linux machine like maya usually involves connecting through SSH and entering commands into a terminal. Sometimes it’s useful to work with GUI-based applications on the remote machine as well. This page will provide an overview for Linux and Windows users to accomplish this. For the rest of this page, we’ll refer to the machine at your desk as the “local” machine, and the one you’re SSHing to as the “remote” machine. If you have issues creating an X Windows session, please refer to this help page for instructions.

Imagine the following scenario. We’re producing some PDF graphics on maya, and we want to view them (say with the acroread program) without having to transfer them to our local computer first. Let’s see how to do this through SSH. You can download the sample PDF to your account on maya if you’d like to follow along.

Note that the examples on this page show our older cluster hpc as the remote host, but the process is exactly the same for maya.


If your local computer is a Linux machine, it probably doesn’t need additional software. The screenshots below are from Ubuntu 9.04, but any Linux distribution with OpenSSH should behave similarly. If you start a regular SSH session and then try to run acroread, you’ll probably get an error.

No display available to local Linux machine

Let’s start a new SSH session, by using the following command

araim@my-linux-box:~$ ssh -Y

Now if we run acroread, a new window will appear on our desktop.

Remote acroread displayed on local Linux machine

Note that a “-X” may be used instead of “-Y” to make an X connection. There are subtle differences between the two, where use of “-Y” implies a higher level of trust in the remote machine, but may not always be available. You may use both flags together to ensure an X connection is made.

araim@my-linux-box:~$ ssh -XY

There are other options as well such as different encryption schemes, and adding compression. If you’re interested, you might want to check the OpenSSH website.


For Windows users, there are two basic programs you’ll need: a terminal program and an X-server. We illustrate Windows Vista here, but XP should work similarly. You probably already have a terminal program to make basic SSH connections to maya. But for this section, we’ll show how to use:

  • PuTTY freely available terminal client
  • Xming an X-server; public domain version is freely available (get the one called “Xming”, not “mesa” or “fonts”, if you just want to get started quickly).

Download and install both programs to your local machine. Once that’s done, we’ll set up a PuTTY session and enable X11 forwarding.

Set up an SSH connection to maya

Enable X11 forwarding

Make sure to specify “localhost:0” as the X display location, as shown above. If you leave it blank, your performance will suffer noticeably.

If we try to run acroread on our PDF file, we get an error. (And if you haven’t enabled X11 forwarding in the PuTTY session, you’ll get a different error).

Cannot open display when runnning acroread

Now we need to run our X Windows server. Start Xming – you’ll know that it’s running when a black “X” icon shows up in your task area.

Cannot open display when runnning acroread

Now let’s try to launch acroread in the terminal once again. This time a window should pop up with our plot. If your network connection to maya isn’t so great, your X11 window might be slow to update.

Cannot open display when runnning acroread

If the SSH connection is broken or the X-Server is stopped, any open remote X11 windows will close. Also, you might have some trouble logging out of PuTTY until you’ve closed your X windows.

To see the setup in complete detail, here’s a video walkthrough posted by a Youtube user.

Also see the documentation for Xming for many more possibilities.


We’ve seen how to run acroread remotely to view graphics on the server from a local Windows or Linux machine. There are many other uses for X11 forwarding such as: using a graphical text editor like gvim or xemacs, running Matlab or similar tools in a graphical environment, or previewing a LaTeX paper after making some edits.