Skip to content

Installing Raylib

The graphical client depends on Raylib, but does not bundle it. This is the first thing to set up before any make. This page explains why, then gives verified, system-by-system instructions.

How the project uses Raylib

The GUI links Raylib dynamically from a system install. The Makefile's link rule is explicit (gui/Makefile:31):

$(CXX) $(CXXFLAGS) -o $@ $^ -lraylib -lGL -lm -lpthread -ldl -lrt -lX11

Three important consequences:

  1. The project does not provide Raylib. There is no Git submodule, no FetchContent, no find_package, no pkg-config, no copy of libraylib/its headers in the repository. The compiler expects to find raylib.h and libraylib.so already installed on the machine.
  2. The link is Linux-style. The -lGL -lX11 -lrt -ldl libraries reveal a Linux/X11 target (see the Windows section below).
  3. An OpenGL driver is required. Raylib relies on OpenGL, and the team-recolor shader targets GLSL #version 330 (gui/assets/shaders/recolor.frag:1). A driver capable of OpenGL 3.3 / GLSL 330 is therefore needed.

Raylib version not pinned

The project pins no Raylib version — not in the Makefile, not in the docs, not in the binary. Any recent version should work (the API used — InitWindow, DrawBillboardRec, LoadShader, rlDrawRenderBatchActive… — has been stable for a long time), but this remains an area of uncertainty. If you hit a symbol error at link time, prefer building from source (below). See also Known limitations.

Installation per system

1. Install the build dependencies and the X11/OpenGL/audio development libraries. These are the packages Raylib needs to build and link.

sudo apt update
sudo apt install -y \
    build-essential git cmake \
    libasound2-dev \
    libgl1-mesa-dev \
    libx11-dev libxrandr-dev libxi-dev \
    libxcursor-dev libxinerama-dev \
    libwayland-dev libxkbcommon-dev

Why these packages?

libgl1-mesa-dev brings the OpenGL headers and the Mesa driver; the libx11/libxrandr/libxi/libxcursor/libxinerama set covers X11 window management; libwayland-dev + libxkbcommon-dev cover Wayland; libasound2-dev (ALSA) covers audio.

2. The distribution's libraylib-dev may work… or not.

sudo apt install -y libraylib-dev   # try the distro package first

On many distributions this package is missing or too old (Raylib only landed in the official repositories late). When in doubt, or on a link error, go straight to building from source, which is the reliable path.

sudo dnf install -y \
    gcc-c++ git cmake \
    alsa-lib-devel mesa-libGL-devel \
    libX11-devel libXrandr-devel libXi-devel \
    libXcursor-devel libXinerama-devel \
    wayland-devel libxkbcommon-devel
# Raylib package (if available):
sudo dnf install -y raylib-devel

If raylib-devel is unavailable or too old, build from source (dedicated tab).

Arch ships an up-to-date Raylib package, the simplest path:

sudo pacman -S --needed base-devel git cmake raylib

The raylib package installs the shared library and the headers; nothing else is required in most cases.

With Homebrew:

brew install raylib

Linux-style link

The project's Makefile (gui/Makefile:31) references -lGL -lX11 -lrt, which do not exist as such on macOS (which uses the OpenGL / Cocoa frameworks). Building the GUI as-is on macOS will likely fail at link time without adapting the link line. On macOS, prefer running the GUI from a Linux machine or VM. See Known limitations.

The recommended method is WSL2 (Ubuntu): the Makefile targets an X11 link, which matches WSL2's Linux environment exactly.

  1. Install WSL2 + Ubuntu:

    wsl --install -d Ubuntu

  2. In the resulting Ubuntu terminal, follow the Linux (Debian/Ubuntu) tab above (an X server is needed; WSLg, built into recent Windows 11, provides one).

Alternative: MSYS2 (pacman -S mingw-w64-x86_64-raylib) is possible but requires adapting the link line (no native Windows -lX11/-lrt). The project's Makefile targets Linux: MSYS2 is not a tested path here.

Building Raylib from source (the reliable path)

This is the recommended method whenever the distribution package is missing, too old, or causes a link error. We build a shared library (-DBUILD_SHARED_LIBS=ON) to stay consistent with the project's dynamic -lraylib link.

git clone https://github.com/raysan5/raylib.git
cd raylib
cmake -S . -B build -DBUILD_SHARED_LIBS=ON
cmake --build build -j$(nproc)
sudo cmake --install build
sudo ldconfig          # refresh the dynamic linker cache

What is ldconfig for?

sudo make install (or cmake --install) drops libraylib.so into /usr/local/lib. sudo ldconfig refreshes the cache so the linker and the dynamic loader find the library at compile time and at runtime. Without it, you may see error while loading shared libraries: libraylib.so at launch.

Classic make variant

The Raylib repository also supports a direct Makefile build:

cd raylib/src
make PLATFORM=PLATFORM_DESKTOP RAYLIB_LIBTYPE=SHARED
sudo make install RAYLIB_LIBTYPE=SHARED
sudo ldconfig

Verifying the installation

1. Is the library visible to the linker?

ldconfig -p | grep raylib

You should see a line like libraylib.so ... => /usr/local/lib/libraylib.so. If nothing appears, rerun sudo ldconfig, or check the install path.

2. Compile a tiny witness program. Create raylib_check.c:

#include "raylib.h"

int main(void)
{
    InitWindow(320, 240, "raylib check");
    CloseWindow();
    return 0;
}

Compile it with exactly the same libraries as the project:

cc raylib_check.c -o raylib_check -lraylib -lGL -lm -lpthread -ldl -lrt -lX11
./raylib_check

If compilation succeeds and the program exits without error, Raylib is correctly installed and linked — you can move on to building the GUI.

OpenGL error at launch?

If ./raylib_check exits with an OpenGL context error, your driver does not provide OpenGL 3.3 / GLSL 330. This is common in VMs without graphics acceleration; enable 3D acceleration, install the Mesa drivers, or use a machine with a GPU. Without GLSL 330, the team-recolor shader will not load (see Graphics rendering).