mGBA: what the Game Boy Advance emulator actually ships, and how to build it

The problem mGBA solves, and who is actually asking for it

Most Game Boy Advance emulators are built for one thing: put a ROM on screen and keep the frame rate up. mGBA is built for that plus everything around it. The README lists debugging via a command-line interface and GDB remote support compatible with Ghidra and IDA Pro, Lua scripting, IPS/UPS/BPS patching, GameShark and Action Replay snapshot import and export, and recording to video, GIF, WebP and APNG. That set of features points at a specific user: someone doing reverse engineering, ROM hacking, tool-assisted work or regression testing of a homebrew build, not just someone replaying a cartridge.

The second group is people with awkward hardware. Local link cable support is listed, motion sensor and rumble cartridges are supported (usable only with game controllers), and the real-time clock works without configuration. Solar sensor support exists for the Boktai games, and there is Game Boy Camera and Game Boy Printer support. Those are the peripherals that usually get dropped first, and their presence is a fair signal of where the project spends effort.

The third group is anyone on low-end hardware. The README states mGBA is known to run at full speed even on low end hardware such as netbooks, and the system requirements section says any computer that can run Windows Vista or newer should handle emulation. That is a claim from the documentation, not something verified here, but it is specific enough to test cheaply on your own machine.

Two frontends, one core, and the mGBA core inside RetroArch

mGBA ships Qt and SDL ports, described in the README as a heavy-weight and a light-weight frontend. The Qt port is the one with the settings menus, controller remapping and the graphical savestate browser; the SDL port is the smaller build for platforms where Qt is not practical. Both drive the same emulation core, which is why a feature like rewind or frameskip does not depend on which frontend you launched.

The core is also packaged separately: the README states cores are available for RetroArch/Libretro and OpenEmu. That matters for anyone who already runs RetroArch, because it means you can get mGBA's emulation without mGBA's interface. The trade-off is real. RetroArch gives you a unified menu and shader pipeline across many systems, but mGBA-specific surfaces such as the CLI debugger and GDB remote support live in the standalone build, not in a libretro session. If debugging is why you picked mGBA, the RetroArch route removes part of the reason.

The repository layout backs this up: src/ holds the implementation, include/ the public headers, and there is a PORTING.md at the top level alongside CONTRIBUTING.md and a doc/ directory. The presence of a porting document is a hint that embedding the core elsewhere is a supported path rather than an accident.

Building mGBA with CMake on Linux or macOS

The README points downloads at the Downloads section of mgba.io and says the source lives on GitHub. If you want a binary, that is where to get it. If you want to build, the documented requirement is CMake 3.1 or newer, with GCC, Clang and Visual Studio 2019 known to work.

The recommended Unix sequence creates a build directory, configures an install prefix of /usr, then builds and installs. The README notes the result goes into /usr/bin and /usr/lib, and that dependencies found at configure time enable features automatically while missing ones produce warnings and disable the corresponding features.

mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
make
sudo make install

On macOS the steps differ, and the README is explicit that you should not run make install there. It gives a Homebrew dependency line and a configure step that points CMake at the Qt5 prefix.

brew install cmake ffmpeg libzip qt5 sdl2 libedit lua pkg-config
mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=`brew --prefix qt5` ..
make

Watch the configure output rather than assuming success. The README states disabled features are shown after the cmake command, right after the warnings about dependencies it could not find. That list is your actual feature set, and it is the first thing to read when something you expected is missing at runtime.

Docker builds and the Windows path that the README recommends

For cross-platform builds the README calls Docker the recommended way for most platforms. The images are published under the mgba namespace on Docker Hub, covering 3ds, switch, vita, wii, several Ubuntu releases and two Windows targets. You run one from the root of a checkout, and it produces a directory named after the target.

docker run --rm -it -v ${PWD}:/home/mgba/src mgba/windows:w32

According to the README, that command leaves a build-win32 directory with the build products, and substituting another image such as mgba/windows:w64 or mgba/switch produces a correspondingly named directory. To parallelize, the README suggests adding the flag -e MAKEFLAGS=-jN to do a parallel build with N number of CPU cores.

One caveat is documented rather than hidden: on Windows systems older than Windows 10, you may need to configure Docker to use VirtualBox shared folders so the checkout maps correctly into the container's working directory, with issue #1985 cited for the details. For native Windows development the README recommends MSYS2, warns you to pick the 32-bit or 64-bit shell deliberately, and notes the dependency install command downloads over 1100MiB of packages. Budget time for that, not just disk.

Controls, savestates and the features you will actually touch

Default keyboard mappings are A on X, B on Z, L on A, R on S, Start on Enter and Select on Backspace, and the README says many game controllers are mapped automatically. Turbo is holding Tab; rewind is holding Backquote. Frameskip is configurable up to 10, and there are 9 savestate slots, viewable as screenshots rather than as a bare list of numbers. That last detail is a small thing that changes how usable a savestate browser is when you have nine slots across several games.

Rewinding is described as configurable, which is worth reading literally: rewind is not free, and the configuration exists because the memory cost of keeping history is a decision you make. If you enable deep rewind buffers on a low-end machine, the full-speed claim from the README is the first thing likely to stop holding.

Loading from ZIP and 7z files is supported, which removes the usual unpack step. Patch support covers IPS, UPS and BPS. Save type detection is claimed to work even for flash memory size, with a footnote marker in the README, and the accuracy claim carries its own footnote pointing at a missing-features section. Those footnotes are where the honest limits live; the feature bullets above them are the marketing surface.

Where mGBA is the wrong choice

Networked multiplayer link cable support is listed under planned features, not under features. Only local link cable support, meaning two instances on the same computer, is implemented. If your use case is trading or battling between two machines on a network, mGBA does not do it today, and the README gives no timeline. Dolphin/JOY bus link cable support is also planned, so GameCube connectivity is not available either.

Game Boy mapper coverage is uneven, and the README says so with a full partial-support list. MBC6 is missing flash memory write support. MMM01, Pocket Cam, HuC-1 and HuC-3 are partial, with the HuC chips missing IR support. TAMA5 has incomplete RTC support. Sachen MMC2 lacks alternate wiring support, and a long tail of unlicensed mappers (BBD, Hitek, GGB-81, Li Cheng, Sintax) is missing logo switching. If your library is mostly licensed cartridges this will never come up. If you collect bootleg multicarts, it will.

Platform support has edges too. The README lists Windows 7 or newer, OS X 10.9 Mavericks or newer, Linux, FreeBSD, and the console ports. Other Unix-like systems such as OpenBSD are described as known to work but untested and not fully supported, which is a polite way of saying you are on your own if something breaks. And the graphics requirement is not zero: OpenGL 1.1 or newer is required, with OpenGL 3.2 or newer for shaders and advanced features.

Alternatives and the real difference in approach

VisualBoyAdvance and its forks are the obvious comparison, and the difference is not accuracy in the abstract, it is what the project treats as a first-class feature. mGBA ships a command-line debugger and GDB remote support that the README says is compatible with Ghidra and IDA Pro, plus Lua scripting. A frontend-only emulator gives you a window and a save file; you attach your own tooling or you do not have tooling. If you are disassembling a ROM, that gap is the whole decision, and it is the difference between mGBA and a plain player.

RetroArch is a different kind of alternative, not a competitor: it is a host, and mGBA is available as a core inside it. Choosing RetroArch means you get one interface and one shader configuration across many systems, and you get mGBA's emulation. What you give up is the standalone-only surface, particularly the debugger workflow. The two are not mutually exclusive, and there is no reason not to have both installed.

Against emulators tuned purely for speed on very old hardware, mGBA's position is stated in its own README: it aims to be faster and more accurate than many existing Game Boy Advance emulators while adding features others lack. That is a positioning claim, not a measurement. The concrete, checkable parts are the feature list, the mapper support tables and the footnoted limits.

Editorial conclusion

Adopt mGBA if you want a GBA emulator you can also debug: the CLI and GDB remote support are the reason to pick it over a frontend-only emulator, and the Lua scripting plus 9 savestate slots cover most replay and testing needs. Do not adopt it if you need networked link cable play, since that is still listed under planned features and only local (same computer) link cable support exists today. Before you commit, check the Downloads section at mgba.io for your platform, confirm whether your distro or package manager already carries a package so you can skip the CMake build, and read the missing-features footnotes in the README because the accuracy claims are qualified there rather than in the feature list.

Frequently asked questions

Official sources

1. License: MPL-2.0
2. mgba-emu/mgba on GitHub
3. Project website
4. README
5. Releases