Skip to end of metadata
Go to start of metadata


A number of programs with graphical user interfaces (e.g., R, MATLAB) use the X11 system which lets the program run on an O2 computer, but show the graphics on your desktop. Even to activate the graphics devices and plot to files, an X11 session must be enabled.  To do this, you need to have an X11 server running on your desktop, and your SSH connection needs to have X11 forwarding enabled.

If you have SSH X11 forwarding enabled in your SSH client and are running an X11 server on your local system, you can run X11 jobs on the O2 compute nodes. You can either

  • submit an X11 job with the --x11=batch flag, like sbatch -p short -t 0-12:00 --x11=batch --wrap="commands here"
  • start an interactive shell with the --x11 flag, like srun --pty -p interactive -t 0-12:00 --x11 /bin/bash .

X11 Terminology

X11 client
The application being displayed (xterm, XEmacs, Mozilla, etc.) You would run this, e.g., on O2

X11 server
The program that drives the user's display and handles connections from X11 clients. This program runs on your desktop.

X11 client that provides a terminal window

What Not To Do

Do not:

  • use xhost or set the DISPLAY environment variable manually to the name of the system where your X11 server is running. Using SSH X11 forwarding will automate and secure this process for you – see below for details.
  • run applications that can be run directly on the system where you're running your X11 server (xterm, XEmacs, Mozilla, mail readers, etc.). In general, you will get better performance from running these applications locally.* With web browsers, you can easily make a connection to a remote service from a locally running browser.
  • * X11-based editors usually have a facility for accessing remote files. For example, for XEmacs, you can use

SSH X11 Forwarding

Security notice about SSH X11 forwarding

SSH X11 forwarding is often disabled by default in SSH clients because administrative users on remote hosts to which you connect can access your X11 server, which could allow them to observe or manipulate your X11 session (including logging keystrokes).

It is recommended you enable X11 forwarding only for remote hosts where you trust the administrators. If you have a question about Research Computing-maintained hosts, please  email

Microsoft Windows

You will need an X11 server for your desktop, as none are included with Windows.

The easiest solution:

Alternatively, if you want X11 display along with a UNIX-like environment to run on top of Windows (e.g. to run UNIX shell scripts and commands), then we recommend using . The X11 server and OpenSSH client work similarly to those on UNIX-like systems.

Linux, Mac OS X, and other UNIX-like systems

You must have X11 started in order for forwarding to work properly. For most UNIX desktop installations, X11 is the default graphical interface and is already running.

For Mac OS X, X11 is not the default graphical interface and must be installed and started. Install on your Mac and run it whenever you want to use X11 forwarding.

This document assumes

  • that X11 forwarding is not enabled by default. (This is common in modern software distributions because of the security implications mentioned above.)
  • that you are using OpenSSH, which is the most common SSH client on UNIX-like systems.

X11 forwarding from the command line

X11 forwarding can be enabled by adding -XY to the command line:

ssh -XY

Adding -C enables compression of the SSH connection along with any X11 traffic.

X11 forwarding from a configuration file

If you use the same settings for a given host every time you connect, you may find it convenient to list these in your SSH client's configuration file.

The ssh configuration file is located in ~/.ssh/config. For hosts you want to enable X11 forwarding to, add the following to your config file:

ForwardX11 Yes
ForwardX11Trusted Yes

Adding Compression yes enables compression of the SSH connection along with any X11 traffic.

X11 and Slurm

There are several flags that pertain to X11 that are accepted by srun and sbatch:


This is the default, and provides X11 forwarding to the first compute hosts allocated. This is the flag utilized when requesting X11-enabled interactive session, as seen above.


This provides X11 forwarding to the last of the compute hosts allocated.


This provides X11 forwarding from all allocated compute hosts, which can be quite resource heavy and is an extremely rare use-case.


This supports use in a batch job submission, and will provide X11 forwarding to the first node allocated to a batch job.

In general, you should only ever need either first or batch (recall that using --x11 with no parameter defaults behavior to first). If you think you might require last or all, please contact us so we can assist you with setting up your workflow.

Troubleshooting X11 forwarding

Here is the recommended order for troubleshooting X11 forwarding if you're having trouble:

  • If your desktop is a UNIX-like system, make sure you can run an X11 program locally, from the same terminal from which you plan to SSH to the remote host. A trivial program like xlogo is useful for this sort of testing. If you can't display a local X11 client, then remote clients are unlikely to work either.
  • SSH to the remote host. Without doing anything further, type echo $DISPLAY. You should get something like localhost:11.0. (The host name will be that of the remove host and the display number will differ from this example.) If $DISPLAY has no value, you don't have X11 forwarding enabled.
  • At this point, you should be able to run an X11 client program like xlogo on the remote host.
  • If you still have trouble, feel free to email Research Computing at .
  • No labels