Skip to content

Use PyCharm with X11 Forwarding and Run:AI

X11 is a window system for the Unix operating systems. X11 forwarding allows executing a program remotely through an SSH connection. Meaning, the executable file itself is hosted on a different machine than where the graphical interface is being displayed. The graphical windows are forwarded to your local machine through the SSH connection.

This section is about setting up X11 forwarding from a Run:AI-based container to a PyCharm IDE on a remote machine.

Submit a Workload

You will need your image to run an SSH server (e.g OpenSSH). For the purposes of this document, we have created an image named The image runs:

  • Python
  • SSH Daemon configured for X11Forwarding
  • OpenCV python library for image handling

Details on how to create the image are here. The image is configured to use the root user and password for SSH.

Run the following command to connect to the container as if it were running locally:

runai submit xforward-remote -i --interactive  \
        --service-type=portforward --port 2222:22

The terminal will show the connection:

The job 'xforward-remote' has been submitted successfully
You can run `runai describe job xforward-remote -p team-a` to check the job status
INFO[0007] Waiting for job to start
Waiting for job to start
Waiting for job to start
Waiting for job to start
INFO[0045] Job started
Open access point(s) to service from localhost:2222
Forwarding from [::1]:2222 -> 22
  • The Job starts an sshd server on port 22.
  • The connection is redirected to the local machine ( on port 2222

Setup the X11 Forwarding Tunnel

Connect to the new job by running:

ssh -X root@ -p 2222

Note the -X flag.



Copy the value. It will be used as a PyCharm environment variable.


The ssh terminal should remain active throughout the session.


  • Under PyCharm | Preferences go to: Project | Python Interpreter
  • Add a new SSH Interpreter.
  • As Host, use localhost. Change the port to the above (2222) and use the Username root.
  • You will be prompted for a password. Enter root.
  • Make sure to set the correct path of the Python binary. In our case it's /usr/local/bin/python.
  • Apply your settings.

  • Under PyCharm configuration set the following environment variables:

    1. DISPLAY - set environment variable you copied before
    2. HOME - In our case it's /root. This is required for the X11 authentication to work.

Run your code. You can use our sample code here.

Last update: December 1, 2020