Running GUI apps in Docker containers

This is a little guide to run GUI apps in Docker containers on top of a OSX (Docker for Mac)

First of all make sure you have Docker for Mac installed. Once running you should have on the top right corner a Docker icon.

Docker for Mac installation

Since Mac doesn’t come with X11 so we’ll use XQuartz to do the X11 forwarding.

Let’s install it using Homebrew:

brew install Caskroom/cask/xquartz

Once installed logout and login again. This is important otherwise the remote connections will fail to X11.

Let’s launch XQuartz

open -a Xquartz

Run xterm (The tools of Xquartz will be found at “/opt/X11/bin”)

Xterm Instance

Ok, now we launched a Terminal on the X11, using local DISPLAY, let’s get a bit closer to what we’ll do with containers and launch it remotely. Get the local IP address, export it in DISPLAY and launch xterm

ip=$(ifconfig | sed -En 's/;s/.*inet (addr:)?(([0-9]*\.){3}[0-9]*).*/\2/p')
export DISPLAY=$ip:0

Now you got xterm running remotely on your machine but there is a catch, xQuartz knows you’re not actually remotely and permits you to open connections, if you try it from the container it will still fail.

In order to test this before trying with the container, let’s try to launch xterm with root user (NOTE: It is never safe to run GUI apps with root user, this is just to test connection)

sudo su -
ip=$(ifconfig | sed -En 's/;s/.*inet (addr:)?(([0-9]*\.){3}[0-9]*).*/\2/p')
export DISPLAY=$ip:0

You’ll get the following error

No protocol specified
Warning: This program is an suid-root program or is being run by the root user.
The full text of the error or warning message cannot be safely formatted
in this environment. You may get a more descriptive message by running the
program as a non-root user or by removing the suid bit on the executable.
/opt/X11/bin/xterm: Xt error: Can't open display: %s

To fix this you’ll need to do two things

Select XQuartz menu, go to Preferences and Check “Allow connections from network clients”

XQuartz Preferences

This will allow remote connections, but you also need to white-list the ip:

ip=$(ifconfig | sed -En 's/;s/.*inet (addr:)?(([0-9]*\.){3}[0-9]*).*/\2/p')
echo $ip
/opt/X11/bin/xhost + $ip

Now if you try again running the xterm you’ll be able to get a terminal.

Now that we got a X11 configured on our OSX, let’s run firefox inside a container:

docker run -i -e DISPLAY=$ip:0 jess/firefox
Firefox inside Docker
docker run -i -e DISPLAY=$ip:0 jess/spotify

For more GUI examples see:

Docker Captain, Google Developer Expert & Founder of Harbur Cloud Solutions (

Docker Captain, Google Developer Expert & Founder of Harbur Cloud Solutions (