Skip to main content
This quickstart guide will help you build and run your first Raylib game in the container environment in just a few steps.

​
Prerequisites

Before you begin, make sure you’ve completed the prerequisites:
  • Docker installed and running
  • Display access enabled with xhost +local:docker
  • User added to docker group (optional but recommended)

​
Quick Start

1

Clone or download the repository

Get the Raylib Container files from GitHub:
git clone https://github.com/gm64x/RayLibContainer.git
cd RayLibContainer
Or download the repository as a ZIP file and extract it.
2

Build the Docker image

Build the container image with Raylib pre-compiled:
docker build -t raylib_container .
This step will take several minutes as it compiles Raylib from source. The image is built using a multi-stage process with Alpine Linux for minimal size.
The build process:
  • Installs build dependencies (GCC, CMake, Mesa, X11 libraries)
  • Clones the latest Raylib from GitHub
  • Compiles Raylib with optimizations
  • Creates a minimal runtime image with only necessary components
3

Run the container with hardware acceleration

Start the container with GPU access for best 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
If you encounter graphics errors, try the software rendering option in Step 4.
What these flags do:
  • -it - Interactive mode with terminal
  • --rm - Auto-remove container on exit
  • -e DISPLAY=$DISPLAY - Forward display to your screen
  • -v /tmp/.X11-unix:/tmp/.X11-unix - Mount X11 socket
  • -v ./user_code:/app/user_code - Mount your code directory
  • --device /dev/dri:/dev/dri - GPU access for hardware acceleration
4

Alternative: Software rendering (if needed)

If hardware acceleration doesn’t work, use software rendering:
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
Software rendering uses CPU instead of GPU, resulting in lower performance (typically 45-60 FPS vs 300+ FPS with hardware acceleration).
5

Verify graphics connection

Once inside the container, test the display connection:
xeyes
A window with eyes that follow your mouse should appear. If you see the window, your graphics setup is working correctly!Close the xeyes window by clicking the X button or pressing Ctrl+C in the terminal.
6

Compile the example game

Navigate to the user code directory and compile the included example:
cd /app/user_code
gcc my_game.c -o my_game -lraylib -lGL -lm -lpthread -ldl -lrt -lX11
Compiler flags explained:
  • my_game.c - Your source code file
  • -o my_game - Output executable name
  • -lraylib - Link Raylib library
  • -lGL -lm -lpthread -ldl -lrt -lX11 - Required system libraries
7

Run your game

Execute your compiled game:
./my_game
You should see a window displaying “Congrats! You created your first window!” 🎉The example creates an 800x450 window running at 60 FPS. Press ESC or click the close button to exit.

​
The Example Game Code

The included my_game.c demonstrates a basic Raylib window:
my_game.c
#include "raylib.h"

int main(void)
{
    // Initialization
    const int screenWidth = 800;
    const int screenHeight = 450;

    InitWindow(screenWidth, screenHeight, "raylib [core] example - basic window");
    SetTargetFPS(60);

    // Main game loop
    while (!WindowShouldClose())
    {
        // Update
        // TODO: Update your variables here

        // Draw
        BeginDrawing();
            ClearBackground(RAYWHITE);
            DrawText("Congrats! You created your first window!", 190, 200, 20, LIGHTGRAY);
        EndDrawing();
    }

    // De-Initialization
    CloseWindow();
    return 0;
}

​
Next Steps

Now that you have Raylib Container running, here’s what to explore next:

Learn Development Workflow

Understand how to develop games inside the container

Compilation Guide

Learn advanced compilation techniques and flags

Example Walkthrough

Deep dive into the example game code

Platform-Specific Setup

Platform guides for Linux, macOS, and Windows

​
Development Workflow

Here’s the typical development cycle:
  1. Edit code on your host system in the user_code/ directory
  2. Changes sync automatically to the container via volume mount
  3. Compile inside the container using GCC
  4. Run and test your game in the container
  5. Iterate - repeat the process as you develop
You can use your favorite code editor on the host system. Changes are instantly available in the container thanks to volume mounting.

​
Common Issues

You may need to run sudo docker ... if you haven’t added your user to the docker group:
sudo usermod -aG docker $USER
Then log out and log back in for the change to take effect.
Make sure you ran xhost +local:docker before starting the container:
xhost +local:docker
This command needs to be run in each new graphical session.
Try software rendering instead of hardware acceleration:
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
Make sure you’re using all required library flags:
gcc my_game.c -o my_game -lraylib -lGL -lm -lpthread -ldl -lrt -lX11
The order and inclusion of all flags is important for successful linking.
For more detailed troubleshooting, see the Troubleshooting Guide.

​
Using Pre-built Images

Instead of building locally, you can pull the pre-built image from Docker Hub: 
docker pull gmaia325/raylib_container
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 \
    gmaia325/raylib_container
The pre-built image from Docker Hub may not have the absolute latest Raylib version. Building locally ensures you get the most recent Raylib release.

Build docs developers (and LLMs) love

Get started for freeTalk to us