raylib-go: the Go binding that bundles the C source so the build just works

Two ways to link, and the README is upfront about the trade

raylib-go is Go bindings for raylib, which the raylib project describes as a simple and easy-to-use library to enjoy videogames programming. The interesting decision in this repository is not the API surface, which mirrors raylib itself, but how the C library gets into your binary.

The default path is cgo, and the README states the consequence plainly: the raylib C source code is included and compiled together with the bindings, and the first build can take a few minutes. That warning is worth reading twice, because people hit it once, assume something is broken, and then discover their build is simply recompiling an entire C library.

The alternative is purego. The README explains that you can use raylib-go without cgo, which means `CGO_ENABLED=0`, on Linux, macOS, Windows and FreeBSD. Thirty-two bit platforms are not supported, and the shared libraries of raylib, as `.dll`, `.so` and `.dylib` files, are already embedded for Linux arm64 and amd64, macOS arm64 and amd64, and Windows arm64 and amd64. A build tag `raylib_no_embed` or the environment variable `RAYLIB_NO_EMBED=1` disables the embedding.

That last point cuts both ways. It is a genuine deployment win, since there is no system library to install on the target, and it is a genuine portability limit, since you get exactly the platforms someone chose to embed.

System packages, and the first build that takes minutes

If you are on the cgo path, you need the X11 and Wayland development headers that GLFW wants, plus Mesa. The README lists them per distribution.

On Ubuntu or Debian:

apt-get install libgl1-mesa-dev libxi-dev libxcursor-dev libxrandr-dev libxinerama-dev libwayland-dev libxkbcommon-dev

On Fedora the same set appears under different names:

dnf install mesa-libGL-devel libXi-devel libXcursor-devel libXrandr-devel libXinerama-devel wayland-devel libxkbcommon-devel

That list is worth reading as a description of what raylib's windowing layer needs: an OpenGL implementation from Mesa, the X11 extension libraries for cursor, randr and inximama-style hints, Wayland, and xkbcommon for keyboard input.

macOS needs Xcode or the Command Line Tools, which the README notes you already have if you installed Homebrew. Windows needs a C compiler such as Mingw-w64 or TDM-GCC, and you can build inside an MSYS2 shell. The Windows section also carries a practical detail: to remove the console window from a built binary, build with `-ldflags "-H=windowsgui"`.

Once the toolchain is there, installation is one command:

go get -v -u github.com/gen2brain/raylib-go/raylib

That is the whole install story. There is no vendored prebuilt binary step, no version negotiation, and no separate module to fetch.

Build tags are where the platform differences live

The build tag list is long enough that it deserves reading as the project's compatibility matrix. It falls into four groups.

Windowing and platform backends come first. `drm` builds for Linux native Direct Rendering Manager mode, which is how you get raylib running on a Raspberry Pi 4 and similar devices with no display server. `sdl` selects the SDL backend, `sdl3` the SDL3 backend, and `rgfw` the RGFW backend. Then two forcing tags for the GLFW path: `x11` forces X11 compatibility mode when running on Wayland, and `wayland` forces Wayland only. That pair exists because Wayland compatibility is a common source of confusion on Linux desktops, and giving users an explicit override is the right answer to it.

Graphics come next. `opengl43` uses an OpenGL 4.3 backend, `opengl21` uses OpenGL 2.1, and the README notes the default is 3.3 on desktop. `opengl11` uses an OpenGL 1.1 backend for the old-school look. The embedded set is `es2` for OpenGL ES 2.0, which the README says can be used to link against Google's ANGLE, and `es3` for experimental OpenGL ES 3.0 support.

Two more are platform-specific rather than graphics-specific. `noaudio` disables the audio functions entirely, which matters on headless and DRM builds where there is no audio device. `raylib_no_embed` is the purego-only tag that turns off the embedded shared libraries.

Two targets are handled by separate projects rather than tags. WebAssembly bindings live in Raylib-Go-Wasm, which the README says should be largely compatible with this repository, and Android has an example under `examples/others/android/`.

The API is the C API, which is the point

The example the README gives is the canonical first raylib program, and the fact that it is idiomatic Go is the whole appeal:

func main() {
  rl.InitWindow(800, 450, "raylib [core] example - basic window")
  defer rl.CloseWindow()
  rl.SetTargetFPS(60)

  for !rl.WindowShouldClose() {
    rl.BeginDrawing()
    rl.ClearBackground(rl.RayWhite)
    rl.DrawText("Congrats! You created your first window!", 190, 200, 20, rl.LightGray)

    rl.EndDrawing()
  }
}

Note the import alias, which is required because the package is named `raylib`: `rl "github.com/gen2brain/raylib-go/raylib"`. That is the only friction in moving from a C raylib tutorial to Go. Function names match, constants match, the draw-call order matches, and the `defer rl.CloseWindow()` in place of a manual close at the end of `main` is idiomatic Go doing the job C would do with process exit.

The repository tree explains the coverage. Alongside `raylib/` there are `raygui/` for the immediate mode GUI, `easings/` for the easing functions, and `physics/`, so this is not just the core module. The `examples/` directory mirrors that structure with `core/`, `shapes/`, `textures/`, `text/`, `audio/`, `gui/`, `physics/`, `easings/`, `shaders/`, `models/`, `games/` and `others/`, plus its own `go.mod`.

Documentation is on GoDoc, and the README points at the upstream raylib cheatsheet as the faster reference for the API itself.

Cross-compiling from Linux with cgo

Because the C source is compiled alongside the bindings, cross-compilation is a real topic rather than a footnote. The README covers the two targets people usually want from a Linux box.

For Windows you install a MinGW toolchain, then point the Go build at it. The 64-bit case:

$ CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc GOOS=windows GOARCH=amd64 go build -ldflags "-s -w"
$ file basic_window.exe
basic_window.exe: PE32+ executable (console) x86-64 (stripped to external PDB), for MS Windows, 11 sections

The `file` output in the README is there for a reason: it is how you confirm you produced a PE32+ binary rather than something else. Note that it says console, which connects back to the `-ldflags "-H=windowsgui"` tip if you want no console window.

For macOS you install the OSXCross toolchain, and the command gets messier because the deployment target has to be pinned for Apple Silicon:

$ CGO_ENABLED=1 CC=aarch64-apple-darwin21.1-clang GOOS=darwin GOARCH=arm64 go build -ldflags "-linkmode external -s -w '-extldflags=-mmacosx-version-min=12.0.0'"
$ file basic_window
basic_window: Mach-O 64-bit arm64 executable, flags:<NOUNDEFS|DYLDLINK|TWOLEVEL|PIE>

The outer quoting around `-extldflags` matters, and the minimum version differs per architecture, with 10.15 for the amd64 example and 12.0.0 for arm64. If you get this wrong the failure is a runtime error on someone else's Mac rather than a build error on yours, which is the worst kind.

This whole section applies to the cgo path only. The purego path needs no cross toolchain at all, which is its main argument.

What the repository does not tell you

A few things are worth working out for yourself.

There is no version compatibility statement. The README does not say which raylib version the bindings track, so if you need a specific raylib feature you should check the `raylib/` directory against upstream rather than assuming. There are also no tagged releases in this repository, which for a bindings package is defensible, since the upstream C library carries its own version scheme, but it does mean version pinning goes through your `go.mod` rather than a release tag.

The topic tags are android, game-engine, golang, raylib, rpi and video-game, which is an accurate summary of who shows up. Raspberry Pi is called out explicitly in the `drm` build tag description, which is a meaningful hint about the audience.

On licensing, the README says raylib-go is licensed under an unmodified zlib/libpng license, which is permissive and appropriate for a bindings layer that compiles someone else's C code into your binary. The upstream raylib license is zlib too, so there is no conflict, but it is worth reading the LICENSE file directly if you are shipping a commercial title.

Support runs through the `#raylib-go` channel of the Raylib Discord server rather than the issue tracker. With 8 open issues against 2540 stars, that is a healthy ratio, and the repository is not archived with the last push on 2026-08-15.

Editorial conclusion

The decision raylib-go asks of you is cgo or no cgo, and the answer changes your deployment story more than your code does. With cgo you get the raylib C source compiled alongside your package, which means a slower first build and a C toolchain as a build dependency. With purego the shared libraries are already embedded for Linux, macOS, Windows and FreeBSD on both arm64 and amd64, so `CGO_ENABLED=0` builds work out of the box, at the cost of 32-bit support and no way to reach platforms without an embedded binary. Whichever you pick, the API is the same raylib API you would write in C, the examples directory is organised by raylib module, and the build tags let you choose a windowing backend, an OpenGL version or audio on and off. The repository has 2540 stars and 210 forks with only 8 open issues, and the last push was 2026-08-15, so it is being kept current.

Frequently asked questions

Official sources

1. gen2brain/raylib-go on GitHub
2. Issues
3. License: Zlib
4. README