Running Pygame in a Docker container (MacOS)

(August 2019)

When I was going through the Ejo repo again, i tried to dockerize the application like I normally do. But since the app is running Pygame, it presented a different sort of challenge than dockerizing a web server app (WSA), since it’s essentially a GUI application.

I decided to give it a try since early Google results seemed like it was hard, but possible. Turns out I should’ve just stuck to providing a virtual env config and moving on, but the learning experience was worth it.

My machine is a MacBook running Darwin.


If you are running a WSA, all you need to do is expose ports to your host machine. But for a GUI app, you need to give the container access to your video graphics driver so it can, in simple terms, share it’s screen with the host.

To do this on my machine, I had to install XQuartz and set the DISPLAY environment variable, which is <host-ip:0>. This post contains more in-depth explanation of how to get this done on a Mac.

Since you can’t set host directories for volumes in a Dockerfile, I had to use a compose file.

version: '3'

    build: .
      - /tmp/.X11-unix:/tmp/.X11-unix
      - .:/usr/src/app

Attempt #1 - Python27 install

FROM python:2.7

RUN apt-get update && apt-get install -y python-dev python-setuptools

WORKDIR /usr/src/app
COPY requirements.txt ./
RUN pip install -r requirements.txt
COPY . .

CMD ["python", ""]

The base image for Python 2.7 is a debian image, so we know we’re working with a Linux distribution. The result? Doesn’t work at all because Pygame has no video driver set.

Attempt #2 - Python 27 install with x11 as Pygame driver

I found this example, that tries explicitly set the video driver for Pygame, which in our case should be x11 since we’re trying to use xhost.

drivers = ['x11', 'directfb', 'fbcon', 'svgalib']

found = False
for driver in drivers:
    if not os.getenv('SDL_VIDEODRIVER'):
        os.environ['SDL_VIDEODRIVER'] = driver
    except pygame.error:
        print 'Driver: {0} failed.'.format(driver)
    found = True

if not found:
   raise Exception('No suitable video driver found!')

Doesn’t work because Pygame doesn’t recognise x11 or any of the others as a video driver. Starting to think this was an issue with the version of Python I was using, I decided to try Python3.

Attempt #3 - Python3 install with x11 Pygame driver

Cant get python 3 to work with Pygame 1.9.2. Had to upgrade to Pygame 1.9.5 to get the install to work.

After install, Pygame still complains that no video driver is found.

Attempt #4 - Python3 install with x11 Pygame driver and libsdl driver

I found all these libsdl packages in a docker file for another app supposedly running Pygame in a container and added them to the python3 install.

FROM python:3

WORKDIR /usr/src/app

RUN apt-get update && apt-get install -y \
    python3-dev -y \ 
    python3-setuptools -y \ 
    python3-numpy -y \ 
    python3-opengl -y  \ 
    libsdl-image1.2-dev -y \ 
    libsdl-mixer1.2-dev -y \ 
    libsdl-ttf2.0-dev -y \ 
    libsmpeg-dev -y \ 
    libsdl1.2-dev -y \ 
    libportmidi-dev -y \ 
    libswscale-dev -y \ 
    libavformat-dev -y \ 
    libavcodec-dev -y \ 
    libtiff5-dev -y \ 
    libx11-6 -y \ 
    libx11-dev -y \ 
    fluid-soundfont-gm -y \ 
    timgm6mb-soundfont -y \ 
    xfonts-base -y \ 
    xfonts-100dpi -y \ 
    xfonts-75dpi -y \ 
    xfonts-cyrillic -y \ 
    fontconfig -y \ 
    fonts-freefont-ttf -y \ 
    libfreetype6-dev -y 

COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .

CMD ["python", ""]

Result? Same error.

Conclusion? Don’t run in a container.

The methods above should work on a Unix distribution like Ubuntu, but because of the limitations MacOS places on accessing hardware drivers, it’s best to just install Python on your OSX machine and install pygame.

It’s as simple as pip install pygame and python or what your file name is.

Please note:

Hi! My name is Opeyemi. I like distributed systems, NodeJS, Golang and Puff Puff. You can learn more about me or message me on Twitter.

Share on