Getting started

Downloading, building and making your own games with Butano is easy and doesn't take too much time, pinky promise.

Supported platforms

Butano is built on top of the devkitARM toolchain, so it supports Windows, macOS and Unix-like platforms.

GBA emulator

Before anything, it is convenient to have a GBA emulator at hand, so you don't have to test in real hardware each change you make in your project.

For developing GBA games, mGBA and the debug version of No$gba are recommended.


The next step is to download and install devkitARM from devkitPro:

  • Install the GBA Development component.
  • Install all members in the gba-dev group if the installer asks for which members to install.
  • Make sure that with the console you are able to build and run some of the examples located in /path/to/devkitpro/examples/gba. By default, devkitARM is installed in C:\devkitPro\ on Windows and in /opt/devkitpro/ on Ubuntu.
  • In particular, you should build and run the Maxmod example located in /path/to/devkitpro/examples/gba/audio/maxmod before going on.


To execute some of the tools needed to include image and audio files in your project, you are going to need Python.

If you are going to install Python on Windows, remember to add it to the PATH and to close all command line windows before installing it:


Both Python 2 and Python 3 are supported for now, but Python 2 is not going to be supported for too long. Make sure you can execute Python from the command line:



Download or clone the latest Butano release from GitHub and put it in a path without spaces or anything weird like that, please.

Butano examples

Butano contains multiple examples of most aspects of the engine.

Make sure that you are able to build and run some of them. They are located in /path/to/butano/examples/. To build an example, open the console, cd to the folder of the example you want to build and type make -j8 if your CPU has 8 cores, make -j16 if it has 16 and so on.

When trying to build the sprites example, if everything went as expected, a sprites.gba file should have been generated in the sprites folder, and the console should show something like this:


Make your own GBA game!

If you were able to build and run some examples, congrats! Now you can make your own GBA game with Butano. To do that:

  • Copy the template project located in /path/to/butano/template/ to a path without spaces nor weird characters.
  • Change the ROM title, the path in which Butano is located and more in the Makefile.
  • cd to the new folder.
  • Type make -j#cpu_cores# again.

If everything went as expected, a *.gba file should have been generated in the project folder! Now learn how to import your assets in the game and also take a look at the modules page. The frequently asked questions (FAQ) are worth a look too.