Please do not post a support request without first reading and following the advice in

How to install the PICO-8 on Retropie for dum-dums

  • Banned

    Installing the fabby Pico-8 pseudo-computer on Retropie is actually really really easy, although you'd never know that from trying to follow any of the hideously confusing and complicated "tutorials" on the subject.

    The short version is "Copy a folder over, edit ES_SYSTEMS.CFG and add some games", but here's a step-by-step hand-holding guide that even idiots like me should be able to follow.

    YOU WILL NEED: $15 and a keyboard connected to your Pi.

    1. BUY PICO-8

    It's not free, but it's only 15 bucks (or less than 12 of the Queen's English Pounds) and that includes hundreds and hundreds of games, so hey. Get it from here:


    When you pay you'll get a link to a page (the one above, in fact) with loads of versions including the Pi one, but no sort of installation instructions whatsoever. Download the Pi version and you'll get a file that unzips to a folder called pico-8 with six files in it:



    Copy the entire folder over to /home/pi (so that you now have /home/pi/pico-8 with the six files in it).


    Add the following lines to your ES_SYSTEMS.CFG file, which is located in /opt/retropie/configs/all/emulationstation:

        <extension>.sh .p8 .png .SH .P8 .PNG</extension>
        <command>/opt/retropie/supplementary/runcommand/ 0 "/home/pi/pico-8/pico8 %ROM%"</command>


    Pico-8 "cartridges" come in .P8.PNG file format. You can download them from all sorts of places including the Lexaloffle BBS. Stick a few into the /home/pi/pico8 folder.

    (If you have none to hand, see the appendix to this guide.)


    I have no idea what this is, but it appears to be necessary and it's the only marginally fiddly part of the process. Quit EmulationStation so you're looking at the Pi $ prompt. Type this:

    sudo apt-get install wiringpi

    It should install in a few seconds. Reboot your Pi.


    At this point Pico-8 should show up in the ES menu as a list of the games (in .P8.PNG format) you added in Step 5. Pick one and fire it up. It should boot to a screen something like this:


    That's yer actual game code. (You can hit Esc to toggle between that and the main Pico-8 prompt if you like.) But you don't need to worry about the technicalities - at this point just hit Ctrl+R on the keyboard and the game will fire up.


    And off you go! Games control with the joystick and the A and X buttons. To quit back to EmulationStation, press Command+Q (or Windows+Q depending on your keyboard).

    NB At the time of writing, whenever I boot a game the Pi flashes up a message about being unable to access the path /dev/dri. I haven't a clue why it does that or what it means, but it doesn't appear to affect anything, so if you get it too just ignore it.


    If you don't have any .P8.PNG files, you can start Pico-8 by clicking the lexaloffle-pico8.png file that comes with the emulator. In my experience it'll display an error message on the Pico-8 screen (see pic below), but that doesn't matter because the important thing is that you'll be in.


    From the command prompt you have a couple of useful getting-started options.

    One is to type INSTALL_GAMES, which will install a small handful of example games for you to try. Another is to type SPLORE, which gets you into the Pico-8 file explorer, which is entirely controlled with the joystick and A button and gives you access to hundreds of games on the Lexaloffle BBS (assuming your Pi is hooked up to the internet).

    A fun trivia fact is that because Pico-8 games are stored as PNG files, you can actually use them as box shots in Emulation Station. For some reason it doesn't work if you just tell GAMELIST.XML to look at the file itself in /home/pi/pico-8, but if you open gamename.p8.png in any picture-editing prog and save it out as newname.png, you can pop the new version in /opt/retropie/configs/all/emulationstation/downloaded_images and use it as your menu image.


    And from that point, folks, you're on your own.

  • @SpudsMcToole hey! Thanks for the post it’s just what I needed!
    Although I have a pre-made image on an sd card for a retropie handheld , I cannot find the /pi/home folder? When o look on the pc it’s just the bios, config, screenshots and roms folders?
    Do I need to SSH into the pi from my pc to put the PICO-8 folder in there??
    Looking forward to hearing from you soon! Thanks

  • @SpudsMcToole I've followed the steps and can see pico-8 on the emulation station menu and have the lexoLoffle cart listed but when I select it screen, runcommand popsup then goes menu does not start Pico 8 or the cart.

    Any help appreciated

    Thanks in advance.

  • Banned

    @bobuk1973 What does RUNCOMMAND.LOG (in /dev.shm) say?

Contributions to the project are always appreciated, so if you would like to support us with a donation you can do so here.

Hosting provided by Mythic-Beasts. See the Hosting Information page for more information.