Recalbox Raspberry Pi Retro Gaming

I’ll be first to admit that I’ve been putting off setting up a Raspberry Pi for my wife to use for retro gaming. I knew there were a few games she missed but Mario Kart 64 was the big one. I’ll also be first to point out that setting up a RetroPi isn’t difficult with the correct setup guide. I will, however, point out that configuration can be time-consuming…unless you have all of your ducks in a row. This means you’re remembering to configure Bluetooth if you’re using Bluetooth controllers, you’ve verified you’re setup to add games wirelessly via your LAN and other minor considerations that are easy to overlook. Basically, you need to make sure your have all of your hardware handy and the ROMs ready to go.

Since everyone and their mother seems to flock to RetroPi, I decided to try something different called recalbox. It shares many of the same features as RetroPi and other solutions like it but I found recalbox to be a brain-dead simple way to get into retro gaming immediately. Note: RetroPi is a good option for those needing maximum customization.

Important: As cool as recalbox is, it has issues with its documentation. Recalbox.conf mentions “Network”, which should be “Wifi” (without quotes). This article will also help you overcome the known WiFi WPA bug using two methods instead of one, plus you’ll also learn how to get N64 games running as well.


This is the hard part – ready? Download, unzip to your micro SD card, boot/select/install/run. That’s all there is to it. Just select recalboxOS with your space key and install with the “letter i.”

In a perfect world, you just happen have some XBox360 controllers laying around. If you do, just plug and play! For those of us who don’t own console gaming rigs, I’ve had great success with Logitech Gamepad F310 controllers. I own two of them, with USB extension cables and while they’re unwieldy, they work really well.

I should point out that if you use the XBox360 controllers you won’t have to configure the controllers. Using the Logitech option means you will. This matters because not all of the button configurations will work as expected. Pressing down on the sticks for example, won’t take. Nor will one of the trigger buttons. Pressing either of these options simply skips that part of the configuration. Those hiccups aside, I would recommend the controllers “overall” as a low-cost solution.

First impressions

I’ve seen video of EmulationStation in the past, but man, I had no idea how slick it looked in real life! Even though the games provided by default aren’t anything to get excited about, having ROMs for each game platform category allows the EmulationStation UI to show off what is available. In order for EmulationStation to show off what is available. In order for EmulationStation to display each category/platform, at least one ROM matching that platform must be present in the corresponding directory.

Once you get a handle on the controls and tour the various emulators installed, the next logical step was to add my ROMs to my recalbox installation.

Getting WiFi running and adding ROMs

One of the things I discovered early on was what a pain it was to get connected to the WiFi. Having used vanilla Raspbian previously, I knew the dongle I had connected was compatible. The obvious fix was to edit:


located in:


How you decide to connect is up to you. Some people have found it’s easiest to just pop out the micro SD card and browse to the conf file from their main PC using a card reader. Being too lazy myself to pull my case apart just to retrieve my micro SD card, I instead opted to do the following:

From the EmulationStation screen where I select the games to play, I grabbed my iPazzPort keyboard/touchpad and got myself into a command prompt by first pressing F4, then ALT+F2.

If you’re looking at this on a large TV, the next step is going to be really small and located in the upper left corner. Your default login is as root and looks like this:

User: root

Password: recalboxroot

From here, I’m able to browse to my conf file using nano.

nano /recalbox/share/system/recalbox.conf

With both the nano and micro SD card to PC method, the text you’re going to be looking for is WiFi (case sensitive).

# ------------ B - Wifi ------------ #
## Set direclty your WiFi key and ssid here
;WiFi_ssid=new ssid
;WiFi_key=new key

Change new ssid and new key to match your own WiFi settings. Save and then reboot. Should this not work for some reason, you may have to resort to removing the card as described above and browsing to your /etc/wpa_supplicant/wpa_supplicant.conf for manual editing. If the former didn’t work, this solution will work so long as you follow the right format.

Here’s mine for example:




Save this and reboot. You’ll connect to your wireless network if you’re using WPA (WiFi Protected Access) for router WiFi security and your router is handing out IP addresses correctly.

Now that we have the recalbox connected, let’s add those ROMs! From your file manager, browse to your Samba shares:


One of the directories you’ll see listed is going to be named RECALBOX. Click into this directory and you’ll be presented with a list of directories that reflect various emulators and functions. Everything from XBMC to System files are listed here. Some of these directories will be easily recognizable while others are going to look rather strange. The easiest way to navigate this is to click into each directory and read the “readme”files provided. For example, famicomdisksystem represents the Japanese NES system while mastersystem represents the Sega Master System.

To make ROMs readily accessible to your Pi, simply drag and drop them into the correct directory representing the correct system emulator.

Pro-tip: After adding ROMs to their corresponding directories, make sure to reboot your Pi. This will ensure the games appear. Also, not all games are going to run perfectly. Atari, NES, SNES, Sega Master System and other older systems will run fine. PSX (Playstation 1), GameGear and others are hit and miss. Also, some emulators will require specific BIOS to work. Easiest way to know for sure: when you see a game goto black screen/start and stop when executed. For the sake of simplicity, older system based emulators will generally be free of this. Some hand-held system emulators can be an exception. The RetroPi wiki has a fairly decent roundup that you can browse through.

N64 won’t work out of the box!

Depending on bug fixes and emulator release cycles, this issue may be fixed by the time you read this. However as things stand now, it’s still a problem. With my current recalbox installation, trying to play N64 games leads to a whole lot of “NOPE” and that can be pretty frustrating.

Before I provide you with my N64 fix, understand the following: this will NOT work on all games. Some N64 games simply won’t work at all. And even with those that do, some understandable audio stuttering can still take place. The two games I’ve had success with are Mario Kart 64 and Super Mario 64. To date, I’ve not had any success with games like Paper Mario. Then again, I haven’t looked too deeply into what’s causing the problem, either.

To get your N64 emulator working with Mario Kart 64 and Super Mario 64, do the following. First, SSH into your recalbox (so you can do this from your desk). Then do the following:

cd ../recalbox/scripts
cp emulatorlauncher.bk

(This ensures even if you do something foolish, you can restore your launcher easily)


Look for the very first instance of:

if [[ "$emulator" == "n64" ]]; then

Immediately below or beside this, you’ll see:

/recalbox/scripts/ 4

You need to change the 4 into a 2. Once you’ve done this, do a Ctrl+X and then press Y.

Important:DO NOT use nano’s search function to locate this entry. I’ve tried this and found it actually made changes to the file for some reason – phantom characters or something similar. Just scroll and look for the first instance of code as stated above.

Once you’ve done this, simply reboot the Pi from SSH to make sure the changes take effect.


Hit the enter key and you’re all set!

SSH settings and security considerations

By default, recalbox has its users running as root and with a password SSH connection. Secure, it’s not. The default login (mentioned previously) is:

User: root
Password: recalboxroot

As I’ve talked about in the past, setting up SSH keys on a Linux system needs to rely on SSH keys and not merely a password. Use the aforementioned link as your guide for correcting this issue. By using authorized keys, you’ll make your recalbox installation much more secure.

Should you choose to retain a password protected SSH setup instead, then at the very least make sure you’re not leaving the WiFi dongle plugged in. I generally don’t recommend security by obscurity, but this will reduce the “attack window” that brute force attacks have to work with.

Closing thoughts about recalbox

As happy with recalbox as I am, my wife swears by it. Each day she returns home and immediately boots up the Pi. She insists that the two of us playing Mario Kart 64 in battle mode does wonders for our marriage. Personally, I believe she’s just looking for an excuse to fling turtles in my general direction.

Joke aside, recalbox is great and it comes highly recommended. Despite its attempt at a fool-proof setup however, there are tweaks that need to be made in order to have an outstanding gaming experience. If you have the ROMs, free time and an interest in retro-gaming, recalbox is a heck of a platform.

FTC required disclosure of Material Connection: The Amazon and Ebay product links in the post above are “affiliate links.” This means if you click on the link and purchase the item, Freedom Penguin will receive an affiliate commission.

Matt Hartley
Freedom Penguin’s founder & talking head – Matt has over a decade working with Linux desktops, his operating system experience consists of both Windows and Linux operating platforms. In addition to writing articles on Linux and open source technology for and, Matt also once served as a co-host for a popular Linux-centric podcast.

Matt has written about various software titles, such as Moodle, Joomla, WordPress, openCRX, Alfresco, Liferay and more. He also has additional Linux experience working with Debian based distributions, openSUSE, CentOS, and Arch Linux.


    1. It’s really tricky to locate when looking via a console editor like nano. Feels almost hidden. First, backup the file. Then with the original, arrow around a bit side to side. Here in a day or so, I’ll try to make a quick console video capture showing you how to find it. The key is less about up and down and more about following the lines of code left to right.

      1. Thanks Matt! I actually just got it working. I dumped a bunch of games in and the emulators appeared. Only thing is, the games are in a few extra folders in the emulation station so when I brownse the games list, there is a ROM folder then the games appear in that. Is there a way to get rid of that folder? There is also a few NES/SNES folders as well.
        Thanks again!

        1. And remember, that 4 to a 2 must be changed or n64 will blackscreen. And of course, playable games for that console will at times have choppy audio. The video is smooth as butter on a Pi2 though. Games successfully working for me are Mario Kart 64 and Super Mario 64. Paper Mario is a fail, so test it with Mario Kart 64 and Super Mario 64.

          1. Thanks! I’ll try those xbox controller links. Ahh… right. mario kart does work but I think the sound was kinda weird… Maybe I should try changing the 4 to 2 again. Thanks!

          2. The 2 to 4 does nothing for sound. It only means video or no video. Sound is because it’s running on a Pi with the given emulator. 😉

          3. hey Matt,

            so i put in the heat sinks and mario kart still freezes when playing 2 player mode. Think maybe I need another power hub to power a second controller?

            Also, I still can spot to change 4 to a 2. Here is what i see:

            login as: root

            root@‘s password:

            [root@RECALBOX ~]# cd ../recalbox/scripts

            [root@RECALBOX scripts]# cp emulatorlauncher.bk

            [root@RECALBOX scripts]# nano

            GNU nano 2.4.2 File: Modified


            [ Unknown Command ]

            ^G Get Help ^O Write Out ^W Where Is ^K Cut Text ^C Cur Pos ^Y Prev Page

            ^X Exit ^R Read File ^ Replace ^U Uncut Text^_ Go To Line^V Next Page


            declare -A ratiomap









            ^G Get Help ^O Write Out ^W Where Is ^K Cut Text ^C Cur Pos ^Y Prev Page

            ^X Exit ^R Read File ^ Replace ^U Uncut Text^_ Go To Line^V Next Page


            ^G Get Help ^O Write Out ^W Where Is ^K Cut Text ^C Cur Pos ^Y Prev Page

            ^X Exit ^R Read File ^ Replace ^U Uncut Text^_ Go To Line^V Next Page

          4. As stated before, the numbers litteraly do not affect performance. Try it and you’ll see a black screen. It’s not affecting anything. It’s a moot point. You keep asking and I keep telling you, it doesn’t change performance. It’s video on or off. 🙂

            Regarding freezing, you’re possibly not giving it enough power (electricity). What kind of power plug are you using? Volts? Did it come with a power plug or are you using something else with the Pi 2?

            The last thing would be the SD card. What brand and type (says on the front) are you using? A lower end card can cause issues too

          5. Gotcha!

            I’m using the ac power adapter that came with the pi 2.

            I am using a 32GB ad card (SP). I have another 8GB (Adata) I can try to see if it’s better on there…


          6. That’s a good start. The final possibility is that there was an update to the n64 emulator since I last installed Recalbox. I personally, have never updated Recalbox.

          7. Hey Matt!
            I have a wii u pro controller and I’m trying to use it with a Asus BTu400 dongle with the pi 2. It should work according to forums.. It says no controllers found when I try to add a Bluetooth device in recalbox but kodi does see it just fine. Any ideas?

          8. Trying to use wii u pro controller with recalbox on the rasp pi 2 with the Asus bt400 Bluetooth dongle but I can’t seem to pair it. Is there something else I can do?

          9. Tried a better card but it still freezes when playing Marion kart n64 (2 players). Maybe because 2 usb remote controls use too much power?

          10. Having some trouble exiting games now… Not sure why. Esc button on the keyboard no longer works. I can navigate the menu fine before entering a game but as soon as I renter a game all controls fail.

          11. Just noticed controllers start working after about 5 or 6 minutes after the games intro. Seems like it has slowed down a bunch?

          12. This is a reply to all three comments — no idea what is wrong – stuff like this usually happens because of tweaking stuff. I suspect something changed somewhere along the line. I’ve installed this on multiple Pi2s without issue. I’d either start fresh or try the forums. Best of luck. 🙂

          13. You were right… Mario Kart freezes after a few mins. Damn! I’ll try to look again to find that 4. I looked pretty hard… Lol

          14. Weird, never had mine freeze. Only the audio stutter a little. If it’s freezing, sounds like a hardware/heat issue. I’m running mine on a Pi2 with a heat sink applied.

          15. Cool. Thanks Matt!
            I’ll order those. Should I still try to change the 4 to 2 to improve the performance quality?

          16. Sorry if you misunderstood, it has zero to with performance. Changing 4 to 2 is about seeing video on your screen or not when using the N64 emulator.

            Again, nothing in that config file affects performance and quality. Because it’s a little Pi computer, all you can do is disperse heat (heat sinks).

      2. Hey Matt,
        So I dumped some games on using a USB drive and they work! The only thing thats a little weird is the games are in a ROM/NES/SNES folder when browsing the emulators. Is there a way to get rid of those folders?

        Also, I’m having trouble setting up wireless xbox 360 controller and/or wii remotes. Is there a specific command for setting those up?
        thanks again for your help MATT! Much appreciated!

        1. No problem at all. 🙂 To remove the extra consoles not being used from appearing on the TV, remove the roms from the corresponding folders. Any empty game console folder with zero roms will vanish from the TV once you restart the PI.

          360 controllers. Boy, gotta admit this is why I avoided using them and went with USB and long extension cords. I personally have never done and I’ve had a LOT people ask me. Best I can do is this:

          and to find that file…

          Anytime you are getting ready to mess with a file, always

          cp blah.conf blah.bak

          Also, when you’re ready to activate your changes, reboot/restart. Hopefully this helps! 🙂

  1. Hi Matt, I’m having some problems with my logitech f310, it works well but just for about 5 minutes, then it stops working freezing in one button/direction. Do you mind sharing your conf file ? thnx

    1. Need greater detail to help. Game, platform (NES?, etc), how’s the device powered (wall plug/USB to something, battery), is the cord a direct connection/connection to a hub/on an cord extender?

      The issue sounds like it’s losing connection somewhere. Usually a symptom of a USB hub. But fill me on the above details. 🙂

Leave a Reply