Skip to main content

​
Overview

Linux provides native support for Docker containers with graphical output through X11 or Wayland. This guide covers the complete setup process for running the Raylib Container on Linux systems.

​
Prerequisites

Before using the container, you need to configure your host system to allow graphical applications from the container to run and manage Docker without sudo.
This guide assumes you have Docker already installed on your Linux system. If not, install it from your distribution’s package manager or from the official Docker website.

​
Setup Steps

1

Enable Display Access

Allow local Docker containers to connect to your graphics server (X11 or Wayland via XWayland):
# Allow connections from Docker
xhost +local:docker
This command usually needs to be run in each new graphical session or after rebooting the system. You might want to add it to your startup scripts (like .profile, .xinitrc, etc.).
To make this persistent, add the command to your shell profile:
# Add to ~/.profile or ~/.bashrc
echo 'xhost +local:docker' >> ~/.profile
2

Add User to Docker Group

Adding your user to the docker group removes the need to use sudo for Docker commands:
sudo usermod -aG docker $USER
Depending on your Linux distribution configuration, there might be situations where using sudo is still necessary for some tasks, even if the user is a member of the docker group (for example, when interacting with the graphical interface).
After running this command, you must log out and log back in or reboot the system for the group change to take effect.
To verify the group membership:
groups $USER
3

Verify Docker Access

After logging back in, verify you can run Docker without sudo:
docker ps
If this works without permission errors, you’re ready to proceed.

​
Running the Container

This option uses your host system’s GPU for better performance: 
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v ./user_code:/app/user_code \
    --device /dev/dri:/dev/dri \
    raylib_container
Parameter Explanation:
  • -it: Starts the container in interactive mode with a terminal attached
  • --rm: Automatically removes the container when it exits
  • -e DISPLAY=$DISPLAY: Passes the host’s DISPLAY environment variable to the container
  • -v /tmp/.X11-unix:/tmp/.X11-unix: Mounts the host’s X11 socket for graphical communication
  • -v ./user_code:/app/user_code: Mounts your code directory into the container
  • --device /dev/dri:/dev/dri: Maps the Direct Rendering Infrastructure devices for GPU access

​
With Software Rendering (Fallback)

Use this option if hardware acceleration doesn’t work. Performance will be lower: 
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v ./user_code:/app/user_code \
    -e LIBGL_ALWAYS_SOFTWARE=1 \
    raylib_container
If you see errors related to dri, glx, mesa, or graphics drivers when using hardware acceleration, try the software rendering option instead.

​
Hardware Acceleration on Linux

​
Understanding GPU Access

The /dev/dri device provides Direct Rendering Infrastructure access, allowing containers to use your GPU: 
# List available DRI devices
ls -la /dev/dri/
You should see devices like card0, renderD128, etc.

​
Common GPU Drivers

Modern Intel integrated graphics use the iris driver (newer) or i965 driver (older).The container should work out-of-the-box with Intel graphics when using the --device /dev/dri:/dev/dri flag.
AMD graphics use the radeonsi or amdgpu driver.Ensure your host system has the Mesa drivers installed. The container will use them through the mounted DRI devices.
NVIDIA requires additional setup with the NVIDIA Container Toolkit.If hardware acceleration fails with NVIDIA, fall back to software rendering with -e LIBGL_ALWAYS_SOFTWARE=1.

​
Verifying Graphics Connection

Once inside the container, test the graphics connection: 
xeyes
A window with eyes that follow the mouse should appear. You can close it by right-clicking or closing the window normally.
If xeyes works, your display forwarding is configured correctly and you can run Raylib applications!

​
Reverting Configuration

If you need to undo the changes made during setup:
1

Revoke Display Access

xhost -local:docker
2

Remove User from Docker Group

sudo gpasswd -d $USER docker
Remember to log out and log in or reboot afterwards.

​
Security Considerations

Do not change the Docker socket (/var/run/docker.sock) permissions to 666! This is a severe security risk. The correct and secure way to avoid sudo is to add your user to the docker group.
If you accidentally changed the permissions, restore them: 
# Only if you incorrectly changed permissions before!
sudo chmod 660 /var/run/docker.sock
sudo chown root:docker /var/run/docker.sock

​
Troubleshooting

Full error: docker: Cannot connect to the Docker daemon... Permission denied.Solution: You likely haven’t added your user to the docker group or didn’t log out/log in after adding them. Try using sudo docker ... or follow the user group setup step above.
Full error: Error: cannot open display: :0Solution:
  • Check that you ran xhost +local:docker in the current host graphical session
  • Verify the DISPLAY variable is being passed correctly (-e DISPLAY=$DISPLAY)
  • Ensure you’re running from a graphical session, not SSH or TTY
Full error: MESA: error: Failed to query drm device., glx: failed to create dri3 screen, failed to load driver: iris/radeon/etc.Solution: Hardware acceleration isn’t working. Ensure the --device /dev/dri:/dev/dri flag was used. If it still fails, try software rendering with -e LIBGL_ALWAYS_SOFTWARE=1.
Full error: docker: invalid reference formatSolution: Check if the image name (raylib_container) is spelled correctly in the docker run command and that the image actually exists. Verify with docker images.

​
Next Steps

Build the Image

Learn how to build the Raylib Container image

Quick Start

Create your first Raylib project

Build docs developers (and LLMs) love

Get started for freeTalk to us