How to show X11 windows with Docker on Mac

Marc Reichelt
2 min readOct 5, 2017


I never would have thought that I would need this feature. Up until now, I only used Docker to get some non-UI environments running, like a local PostgreSQL database or an Android build environment for GitLab CI.

Right now I am part of a team called ‘Happy Robots’ that works on the final project of Udacity’s Self-Driving Car Engineer Nanodegree. That is: Writing and running code on an actual self-driving car!
For running the code the 3 Mac users in our 5-person team are using a Docker image running the ROS, which is only available for Linux. You might wonder why we would need a UI for running the algorithms, and you are right: We don’t. But we included a dashboard built on the library pygame, which we use to render the track, current waypoints, position of the vehicle, traffic lights and their status and much more later on. This is quite helpful to visualize whether our algorithms behave correctly. Here a snapshot of simulator and the pygame dashboard, running on a native Ubuntu installation of my team mate Simon Ritzel:

Udacity simulator and pygame dashboard, running natively on Ubuntu (without Docker)

To get the pygame running on my Mac, I had to do a few things:

Then I tried out to run a Firefox instance and forward it via X11. The recipe:

Firefox with X11 forwarding on my Mac

And wow, it’s actually running — a Linux Firefox on my Mac! Notice the trick using host.docker.internal as display name. That’s a hostname that points to the host machine, so we don’t have to deal with changing IP addresses.

To get our pygame dashboard running, I just had to do three things:

  1. Ensure localhost is allowed X11 forwarding:
    xhost +
  2. Inside the docker image, install pygame and set the display variable:
    pip install pygame
    export DISPLAY=host.docker.internal:0
  3. Run our algorithm!

Now, let’s have a look at the result:

pygame dashboard running via X11 forwarding

Awesome! This should allow you to run a lot of Linux UI applications on your Mac. Of course some things don’t work and the performance could be improved, too. But it gives you a great starting point! 😊



Marc Reichelt

Developer. Loves Linux, Android & open source. Making the world better, one step at a time!