How to

How to Play Game Boy Games in Your Linux Terminal

The Linux terminal, while certainly a fun place, isn’t especially well known as a console gaming platform—largely thanks to its limited ASCII and Braille output. But its Spartan interface is almost perfect for replicating the display of an original 1989 Nintendo Game Boy. Here’s how to play Game Boy games in your terminal.

Why Emulate a Game Boy in the Terminal?

pokemon red star splash screen in the linux terminal

Nintendo’s Game Boy is one of the most wildly successful game consoles ever created, and introduced generations of kids and adults to the joys of games such as Tetris, Pokemon, and the Super Mario Land series.

With its 4MHz processor and 47x43mm display, the Game Boy could easily fit in your trouser pocket and offered around 15 hours of gameplay from four AA batteries. In the late 1980s and early 1990s, the Game Boy was a must-have accessory for any teenager, and utterly dominated the portable gaming market.

The console’s popularity and longevity meant that there were thousands of officially licensed Game Boy games, with many more hacked together by bedroom tinkerers.

By running an emulator in your terminal, you can run every single one of these, transforming your terminal into an extensive library of playable games.

As the name suggests, php-terminal-gameboy-emulator is written in PHP—a language usually used to create websites—and although the project’s readme only states that it supports PHP 5.6, PHP 7, and HHVM, we’ve had it running almost flawlessly on PHP versions up to 8.2.

With php-terminal-gameboy-emulator, you’re not limited to your computer either and can run sessions over Secure Shell (SSH) on remote machines.

Because it’s running in a terminal, your Game Boy games won’t have any sound, but we’re sure you can hum the Tetris theme tune.

You also won’t be able to save games. If these limitations are too restrictive, there are dozens of excellent emulators available on Linux.

You should only use ROMS you legally own. You can find a huge variety of homebrew Game Boy ROMS at Homebrew Hub.

How to Install php-terminal-gameboy-emulator on Linux

Before you install php-terminal-gameboy-emulator, you should first make sure you have PHP installed. To check this, open a terminal and enter:

 php -v 

This command should return the version number of your installed PHP package. If it returns “php: command not found”, you do not have PHP installed.

To install PHP on Arch and related distros, enter:

 sudo pacman -S php 

On Debian and its derivatives:

 sudo apt install php 

For the Fedora family, you first need to add the Remi PHP repository:

 sudo dnf -y install 

…where XX is your Fedora version number. Now enable the repository:

 sudo dnf module enable php:remi-8.1 -y 

Finally, you can install PHP with:

 sudo dnf install php -y 

Now PHP is installed, use the wget tool to download php-terminal-gameboy-emulator:


Make it executable with:

 sudo chmod +x php-gameboy.phar 

Move the binary to your path so it’s executable from anywhere on your system;

 sudo mv php-gameboy.phar /usr/local/bin/php-gameboy 

Play Awesome Game Boy Games in Your Linux Terminal

To start a game with php-terminal-gameboy-emulator, you need to pass the filename of the ROM file as an argument. For instance:

 php-gameboy ~/gbroms/ 

The ROM will load almost instantly, and you’ll be faced with the familiar grayscale splash screen of whatever game you choose.

In the video below you can see that the emulator is quite capable of running Street Fighter II and that this writer is just as handy with with the terminal version as he is with the genuine handheld—convincingly controlling Ryu to beat Guile in the first round.

You’ll also notice that while php-terminal-gameboy-emulator does a convincing job of recreating the Game Boy’s dot matrix screen in your terminal, there are occasional visual artifacts. How often these appear, and their seriousness will depend on the game you’re playing.

The emulator controls are as follows, and unfortunately can’t be remapped:

Keyboard Controls

Console Controls


D-Pad directions

Comma (,)


Dot (.)






Impress Your Friends With php-terminal-gameboy-emulator!

Playing action, fighting, and adventure games from within the Linux terminal is a technical feat that’s sure to inspire your colleagues and relations, and can be an excellent way to convince them of Linux’s pre-eminence as a gaming system.

You can also use it as a way to relive your childhood in some idle downtime when you’re working.

Leave a Reply

Your email address will not be published. Required fields are marked *