Installation

Installation

Requirements

• Go 1.26 or later
• SDL2 development libraries — go-gui uses SDL2 for windowing, input, and audio. The specific packages required depend on your OS.

---

macOS

Install dependencies via Homebrew:

brew install go pkg-config sdl2 sdl2_mixer freetype harfbuzz pango fontconfig

---

Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y \
  golang build-essential pkg-config \
  libsdl2-dev libsdl2-mixer-dev libfreetype6-dev libharfbuzz-dev \
  libpango1.0-dev libfontconfig1-dev

---

Fedora / RHEL

sudo dnf install -y golang gcc pkgconf-pkg-config \
  SDL2-devel SDL2_mixer-devel freetype-devel harfbuzz-devel pango-devel fontconfig-devel

---

Arch Linux

sudo pacman -Syu --noconfirm go base-devel pkgconf \
  sdl2 sdl2_mixer freetype2 harfbuzz pango fontconfig

---

Windows — MSYS2 / MinGW x64

Install MSYS2, then from the MSYS2 MinGW x64 shell:

pacman -S --needed \
  mingw-w64-x86_64-go mingw-w64-x86_64-gcc \
  mingw-w64-x86_64-pkgconf mingw-w64-x86_64-SDL2 \
  mingw-w64-x86_64-SDL2_mixer mingw-w64-x86_64-freetype \
  mingw-w64-x86_64-harfbuzz mingw-w64-x86_64-pango \
  mingw-w64-x86_64-fontconfig

Use the MSYS2 MinGW x64 shell for go build and go run.

---

Windows — vcpkg

vcpkg install sdl2:x64-windows sdl2-mixer:x64-windows \
  freetype:x64-windows harfbuzz:x64-windows pango:x64-windows \
  fontconfig:x64-windows

Set CGO_CFLAGS and CGO_LDFLAGS to the vcpkg include and lib paths before building.

---

Get the module

go get github.com/go-gui-org/go-gui

---

Verify the install

Run the minimal example to confirm SDL2 is wired up correctly:

go run github.com/go-gui-org/go-gui/examples/get_started@latest

Or, after cloning the repository:

go run ./examples/get_started/

A small window with a click counter should appear. If you see it, everything is working.

For a full tour of the widget library, run the showcase:

go run ./examples/showcase/

---

Backend selection

backend.Run(w) automatically selects Metal on macOS and OpenGL on Linux/Windows. To target a specific backend explicitly:

import "github.com/go-gui-org/go-gui/gui/backend/metal" // macOS, Metal
import "github.com/go-gui-org/go-gui/gui/backend/gl"    // cross-platform, OpenGL
import "github.com/go-gui-org/go-gui/gui/backend/web"   // WASM / browser
import "github.com/go-gui-org/go-gui/gui/backend/ios"   // iOS, Metal + UIKit

For headless testing (CI, unit tests) the gui/backend/test no-op backend runs all layout and widget logic without a display server.