Skip to main content
Before using Raylib Container, you need to configure your host system to allow graphical applications from the container to run and to manage Docker without sudo.
If you’re using macOS, follow the MacOS Compatibility Guide for specific instructions on setting up XQuartz instead of the X11 configuration below.

​
Docker Installation

You must have Docker installed on your system. If you don’t have Docker yet:
1

Download Docker

Visit the official Docker website and download Docker Desktop for your operating system.
2

Install Docker

Follow the installation wizard for your platform. On Linux, you can also install Docker Engine directly through your package manager.
3

Verify Installation

Open a terminal and verify Docker is installed:
docker --version

​
X11 Display Access (Linux)

This section applies to Linux users. macOS users should install and configure XQuartz instead.
Graphical applications inside Docker containers need permission to connect to your display server (X11 or Wayland via XWayland).
1

Enable Display Access

Allow local Docker containers to connect to your graphics server:
xhost +local:docker
This command usually needs to be run in each new graphical session or after rebooting the system. Consider adding it to your startup scripts like .profile, .xinitrc, or .bash_profile.
2

Verify DISPLAY Variable

Check that your DISPLAY environment variable is set:
echo $DISPLAY
You should see output like :0, :1, or :0.0.
Adding your user to the docker group removes the need to use sudo for Docker commands.
1

Add User to Docker Group

Run the following command to add your user to the docker group:
sudo usermod -aG docker $USER
2

Log Out and Back In

After running this command, you must log out and log back in or reboot the system for the group change to take effect.
The simplest way is to completely log out of your desktop session and log back in. Alternatively, reboot your system:
sudo reboot
3

Verify Group Membership

After logging back in, verify you’re in the docker group:
groups
You should see docker in the list of groups.
4

Test Docker Access

Try running a Docker command without sudo:
docker ps
If this works without asking for a password, you’re all set!
Depending on your Linux distribution’s specific configuration, there might be rare situations where sudo is still necessary for certain tasks (like opening the display from within a container), even with docker group membership.

​
Graphics Hardware Requirements

For optimal performance, Raylib Container can use your GPU through hardware acceleration:
  • Linux: The container maps /dev/dri devices for Direct Rendering Infrastructure (DRI) access
  • Fallback: Software rendering is available if hardware acceleration doesn’t work
Check if your system has DRI devices available:
ls -la /dev/dri
You should see devices like card0, renderD128, etc. If you don’t see these, you’ll need to use software rendering mode.

​
Security Considerations

Do not change the Docker socket 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 as shown above.
If you accidentally changed the socket permissions, restore them: 
sudo chmod 660 /var/run/docker.sock
sudo chown root:docker /var/run/docker.sock
The default permissions are usually 660 with owner root and group docker.

​
Reverting Configuration Changes

If you need to undo the changes made during setup: 
xhost -local:docker

sudo gpasswd -d $USER docker
Remember to log out/log in or reboot afterwards for this to take effect.

​
Next Steps

With prerequisites complete, you’re ready to build and run the container. Continue to the Quickstart Guide to compile and run your first Raylib game.

Build docs developers (and LLMs) love

Get started for freeTalk to us