Game Boy / Gameboy Color emulator for iOS, Mac, Raspberry Pi, Windows and Linux
C HTML C++ Shell Objective-C TeX Other
Failed to load latest commit information.
platforms New project for Raspberry Pi 3 May 29, 2016
src fixed random crashes in audio subsystem Feb 27, 2016
.gitignore Update .gitignore Mar 21, 2015
.travis.yml Update .travis.yml Jan 8, 2016
LICENSE added license Aug 27, 2012 Update Apr 18, 2016


Copyright © 2012 by Ignacio Sanchez

Build Status

Gearboy is a Nintendo Game Boy / GameBoy Color emulator written in C++ that runs on iOS, Raspberry Pi, Mac, Windows and Linux.

Follow me on Twitter for updates:



  • Highly accurate CPU emulation, passes from blargg's tests.
  • Accurate instruction timing, passes from blargg's tests.
  • Memory Bank Controllers (MBC1, MBC2, MBC3 with RTC, MBC5), ROM + RAM and multicart cartridges.
  • Accurate LCD controller emulation. Background, window and sprites, with correct timings and priorities.
  • Mix frames: Mimics the LCD ghosting effect seen in the original Game Boy.
  • Sound emulation using SDL Audio and Gb_Snd_Emu library.
  • Game Boy Color support.
  • Integrated disassembler. It can dump the full disassembled memory to a text file or access it in real time.
  • Saves battery powered RAM cartridges to file.
  • Compressed rom support (ZIP deflate).
  • Multi platform. Runs on Windows, Linux, Mac OS X, Raspberry Pi and iOS.

Build Instructions


  • Install Xcode for Mac OS X. You need iOS SDK 8 or later.
  • Build the project.
  • Run it on real hardware using your iOS developer certificate. Make sure it compiles on Release for extra optimizations.
  • For jailbroken devices use the jailbreak branch.

Raspberry Pi 2 & 3 - Raspbian

  • Install and configure SDL 2 for development:
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libfreeimage-dev libopenal-dev libpango1.0-dev libsndfile-dev libudev-dev libasound2-dev libjpeg-dev libtiff5-dev libwebp-dev automake
cd ~
tar zxvf SDL2-2.0.4.tar.gz
cd SDL2-2.0.4 && mkdir build && cd build
../configure --disable-pulseaudio --disable-esd --disable-video-mir --disable-video-wayland --disable-video-x11 --disable-video-opengl --host=armv7l-raspberry-linux-gnueabihf
make -j 4
sudo make install
  • Install libconfig library dependencies for development: sudo apt-get install libconfig++-dev.
  • Use make -j 4 in the platforms/raspberrypi2/Gearboy/ folder to build the project.
  • Use export SDL_AUDIODRIVER=ALSA before running the emulator for the best performance.
  • The emulator generates a gearboy.cfg configuration for you where you can customize keyboard and gamepads. Key codes are from SDL.


  • You need Visual Studio 2010 or better.
  • Install the Qt 5 SDK for Windows.
  • Install the Qt 5 Visual Studio Add-in and point it to the Qt SDK.
  • Install and configure SDL 2 for development.
  • In order to use OpenGL extensions I used GLEW. This is because of a bug in QGLFunctions. Make sure the GLEW headers and libs are configured within VC++.
  • Open the Gearboy Visual Studio project and build.

Mac OS X

  • You need Qt Creator, included in the Qt 5 SDK.
  • Install Xcode and run xcode-select --install in the terminal for the compiler to be available on the command line.
  • Install the Qt 5 SDK for Mac OS.
  • Download SDL 2 source code. Then run this commands:
sudo make install
  • Open the Gearboy Qt project with Qt Creator and build.


  • Install Qt 5 development dependencies (Ubuntu: sudo apt-get install qt5-default qttools5-dev-tools).
  • Install OpenGL development dependencies (Ubuntu: sudo apt-get install freeglut3-dev).
  • Install SDL 2 development dependencies (Ubuntu: sudo apt-get install libsdl2-dev).
  • In order to use OpenGL extensions I used GLEW dependencies (Ubuntu: sudo apt-get install libglew-dev). This is because of a bug in QGLFunctions.
  • Move to the platforms/linux/Gearboy/ folder and run qmake -o Makefile && make to build the project.
  • In Ubuntu I had to export SDL_AUDIODRIVER=ALSA before running the emulator for the sound to work properly.

Accuracy Tests

Compared to other emulators: see here.

Tests from blargg's test roms:




Gearboy - Nintendo Game Boy Emulator

Copyright (C) 2012 Ignacio Sanchez

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see