Game Boy / Gameboy Color emulator for iOS, Mac, Raspberry Pi, Windows, Linux and RetroArch

emulator, game-boy, gameboy, gameboy-color-emulator, gameboy-emulator, ios, linux, raspberry-pi
brew install gearboy



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, Linux and RetroArch.

Follow me on Twitter for updates:


  • iOS (Jailbreak): Cydia. You can open rom files from other apps like Safari or Dropbox. They can be placed in /var/mobile/Media/ROMs/GAMEBOY too. Save files are placed in /var/mobile/Library/Gearboy
  • iOS: Build Gearboy with Xcode and transfer it to your device. You can open rom files from other apps like Safari or Dropbox, or use iTunes file sharing.
  • Mac OS X: brew install gearboy
  • Windows: (NOTE: You may need to install the Microsoft Visual C++ Redistributable)
  • Linux: Gearboy-2.3-Linux.tar.gz
  • Libretro / RetroArch: docs
  • Raspberry Pi: Build Gearboy from sources. Optimized projects are provided for Raspberry Pi 1, 2 and 3.
  • Ubuntu Touch version by Ryan Pattison: here


  • Highly accurate CPU emulation, passes from blargg's tests.
  • Accurate instruction and memory timing, passes and 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 including mid-scanline timing.
  • 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, iOS and as a libretro core (RetroArch).

Build Instructions


  • Install Xcode for Mac OS X. You need iOS SDK 8 or later.
  • Build the project platforms/ios/Gearboy.xcodeproj
  • Run it on real hardware using your iOS developer certificate. Make sure it builds on Release for better performance.
  • 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/raspberrypi3/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 2015 or later.
  • Install the Qt 5 Open Source SDK for Windows.
  • Install the QtPackage Extension and point it to the Qt SDK.
  • Open the Gearboy Visual Studio solution platforms/windows/Gearboy/Gearboy.sln and build.
  • You may want to use the platforms/windows/Gearboy/ project file with Qt Creator instead.

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 platforms/macosx/Gearboy/ project file with Qt Creator and build.


  • Ubuntu or Debian:
sudo apt-get install build-essential qt5-default qttools5-dev-tools freeglut3-dev libsdl2-dev libglew-dev
cd platforms/linux/Gearboy
qmake && make
  • Fedora:
sudo dnf install @development-tools gcc-c++ qt5-devel freeglut-devel SDL2-devel glew-devel
cd platforms/linux/Gearboy
qmake-qt5 && make

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