How to install PICO-8 on GameShell



CREDITS GO TO @dddaaannn


PICO-8 is a fantasy console for making, playing, and sharing small games. PICO-8 is a commercial product by Lexaloffle Games LLP. Versions are available for Windows, mac OS, Linux, and Raspberry Pi. The Raspberry Pi version runs on the GameShell, with some set-up.

Follow these instructions to get PICO-8 and install it on your GameShell. It will run in the splore mode, which lets you browse, download, and play PICO-8 games.

Go here to purchase your copy of PICO-8 if you don’t already own it: ($15)

Once purchased, visit the downloads page and download the Raspberry Pi version. This file has a filename similar to:

Tip: Your PICO-8 license includes versions for all platforms. Download the version for your desktop computer, make PICO-8 games of your own, and run them on your GameShell!

Transfering PICO-8 to the GameShell

Connect your GameShell to your wifi network and get its IP address:

Turn on your GameShell.
If necessary, connect the GameShell to your wireless network: Settings, Wi-Fi.
In the main launcher menu, select TinyCloud. This displays the IP address of your GameShell, such as

You can transfer files to the GameShell using scp, a file transfer method based on ssh (Secure Shell). Some file transfer programs know how to do this, such as Putty SCP for Windows, WinSCP for Windows, or Transmit for Mac. Connect using the IP address, an account name of cpi, and a password of cpi.

On Mac and Linux (and also Windows with Putty SCP or the Windows Subsystem for Linux), you can use a Terminal to do this with a command-line interface and the scp command. To transfer PICO-8 to the GameShell using the scp command:

scp cpi@

Enter the password cpi when prompted.

Connecting to the GameShell’s command-line interface with ssh

The steps that follow require running commands directly on the GameShell. On Windows, you can do this with an SSH client such as Putty for Windows. On Mac and Linux, open a Terminal window and use the ssh command. Connect to the IP address with a username of cpi and a password of cpi, as above.

To connect with the ssh command:

ssh cpi@

Enter the password cpi when prompted.

Tip: My GameShell responds poorly over an SSH shell connection like this. Things I type don’t appear right away. It’s frustrating, but if you can get through these next few steps, you won’t need it again.

Installing WiringPi

PICO-8 requires WiringPi to run. It uses this for features that access the GPIO pins on a Raspberry Pi. You probably won’t use this feature with GameShell, but PICO-8 won’t start without it.

At the GameShell Linux command prompt, run these commands:

git clone git://
cd wiringPi

Installing PICO-8

Also at the GameShell command prompt, run this command:


Adding PICO-8 to the Launcher

You will start PICO-8 using a new icon in the Clockwork Pi Launcher interface. To add this icon, run this long command at the GameShell command prompt. (I recommend copy-and-pasting this into your terminal window.)

echo >~/apps/launcher/Menu/GameShell/ SDL_VIDEODRIVER=x11 DISPLAY=:0 /home/cpi/pico-8/pico8_dyn -splore -draw_rect 32,0,256,240

Restart your GameShell. An easy way to do this is to run this command:

sudo reboot

(Your ssh connection will disconnect after running this command. This is normal.)

Tip: The -draw_rect 32,0,256,240 part of this command tells PICO-8 to draw its screen stretched to fit a 256x240 region, with a left margin of 32 pixels so that the 256-wide rectangle is centered on the GameShell’s 320x240 display. PICO-8’s screen is a 128x128 square, so stretching it to a wide rectangle makes it a little wider than intended. You could make this exactly square with -draw_rect 40,0,240,240, but to fit these dimensions PICO-8 has to make every other pixel an odd size. I think 256x240 looks better, but you can experiment to find something you like.

Start PICO-8 for the first time

When GameShell has finished booting and you see the Launcher again, a “PICO-8” icon (a circle with a “Pi” in it) will be in the menu. Select it.

One of two things will happen:

PICO-8 starts with a chime sound, and it appears in a small square. You can use the cursor keys, but you can’t use the ABXY buttons yet.
If this happens, press MENU, then press START to select “shutdown pico-8”.
PICO-8 starts with a chime sound, but you only see the GameShell “Loading” screen.
If this happens, connect to the command prompt via SSH and run this command:

killall pico8_dyn

When PICO-8 shuts down (using either method), it creates its configuration file and some other things. We can edit this file to fix the remaining problems.

Configuring PICO-8

Re-connect to GameShell via SSH to get a command prompt. Run this command to open a file editor with the PICO-8 configuration file:

pico ~/.lexaloffle/pico-8/config.txt

“Pico” is a simple text file editor available on most Linux systems, including GameShell. It has nothing to do with PICO-8, it’s just called “Pico” by coincidence.

Use the cursor keys to scroll down to the line that says fullscreen_method. Edit this value to 0:

fullscreen_method 0
Scroll down further to the line that says button_keys. Edit this value as follows:

button_keys 0 0 0 0 13 14 0 0 0 0 0 0 0
Press Control-O to save the file. Press Control-X to exit Pico.

Optional: Change the Launcher icon


The Launcher icon for PICO-8 works just fine with the default icon (the letters “Pi” in a circle). You can change this to the PICO-8 logo, if you like.

In your browser, download this image file by right-clicking and selecting “Save Image As…” (or the equivalent feature in your browser):

PICO-8 icon

Copy this file to your GameShell using scp or whatever file transfer program you used earlier.

You want this file to be named PICO-8.png, and to be located in the folder /home/cpi/apps/launcher/skin/default/Menu/GameShell. You can either find this location using your file transfer program, or you can transfer the image file to the home directory (/home/cpi/) then move it into place with a shell command. Connect via ssh, then:

mv PICO-8.png ~/apps/launcher/skin/default/Menu/GameShell/

Restart your GameShell (sudo reboot). When the GameShell is finished restarting, the Launcher should have the new icon.

Welcome to PICO-8!

Launch PICO-8 from the Launcher. It should start reliably and at a comfortable size.

Move right to find the “Featured” section. If necessary, press B on [update] to load the list. Move up and down to find a game, then press B to start it.

PICO-8 games use one or both of the A and B buttons. Some games will refer to these as Z and X, or C and V, because these are the default keys on a desktop computer. Games may also refer to them as (O) and (X), which are their “fantasy console” button icons.

To exit a game and return to the Splore game selection menu, press the GameShell MENU button, then select “Exit to Splore”. (You can also use the pause menu just to pause your game.)

To exit PICO-8 entirely and return to the GameShell Launcher, exit to Splore, then press MENU again and select “Shutdown PICO-8”.

Tip: Be careful not to select “Exit to Console” from the shutdown menu. This puts PICO-8 in its game developer mode. It’s a super fun mode, but you need a full keyboard to use it or get back out of it. Connect via ssh and run the sudo reboot command if you get stuck here.

Enjoy the games, and come visit the PICO-8 community in the forum to learn more!



I don’t object to reposting the tutorial to the forum.

[Update: The original post has been edited to remove the offending content.] I strongly object to adding the insinuation that the reader should pirate PICO-8. I explicitly wrote that section to discourage piracy. Please remove this, or remove the post.

I realize that we’re playing a bit loose with copyright on old game ROMs for emulators. PICO-8 is not in the same category: it’s inexpensive commercial software being developed actively by a small software company. Pirating PICO-8 is not the same as sharing old abandoned ROMs. Pirating PICO-8 actively hurts everyone who supports it. If you like PICO-8, pay for it.



Thank you both!

PICO-8 is indeed a closed source, we respect it. It is obviously a GREAT project.

We are also looking for some open source “fantasy computer” or we can DIY one :relaxed:.


Rerverted the first post with content, (as for @dddaaannn I don’t mind it to be here too, some people don’t go to the Wiki) and removed the flagged content (plus a little bit of reformatting)



Works like a charm! Thanks a lot. Was worth the 15 US-Dollars.


PICO-8 won’t start for me from the launcher. I followed every step and have now the PICO-8 icon in my launcher. I even changed the icon to the PICO-8 logo but every time I want to start the program, it boots back into the launcher. The only way I can start PICO-8 is by entering this command via ssh:

echo >~/apps/launcher/Menu/GameShell/
SDL_VIDEODRIVER=x11 DISPLAY=:0 /home/cpi/pico-8/pico8_dyn -splore -draw_rect 32,0,256,240

EDIT: I just discovered that the located in ~/apps/launcher/Menu/GameShell/ was completly empty. I just added the following line to connect the .sh file to the actual program:

SDL_VIDEODRIVER=x11 DISPLAY=:0 /home/cpi/pico-8/pico8_dyn -splore -draw_rect 32,0,256,240


Love it!! Well totally worth the money!!


@ZELSK8 Glad you got it working! It looks like the “echo” statement got split into two lines in this forum repost, which would have the effect you described. As one line, it creates that file with “SDL…” as its contents, which is the intended effect. As separate lines, it would create an empty file (the first line), then separately start PICO-8 (the second line). :slight_smile:

The original doc has this correct. The error is only in this forum repost. Maybe someone with edit permissions can fix it?


If you are enjoying PICO-8, don’t forget to lookup the #pico8 hashtag on Twitter. One of the liveliest programming-focused communities out there.

Whats are your Favourite go to games?

and follow @lexaloffle on twitter too!


I’ve set the first post as a “wiki”, so you should be able to edit it.


Perhaps a n00b question, but after installing Pic8, how do you add games?


@Gryzor: If you are connected to the internet, you should be able to access a selection of popular games in the FEATURED panel:


plus all those available in the BBS ( in the last one. You may need to select UPDATE in the menu for them to refresh.


Ohh fantastic. I didn’t know because I’ve never used it! Going to buy it now…



Ok, bought and installed, great guide and a huge thanks :slight_smile:

One more question - despite the reference to key input in the guide, I find that my YXAB keys don’t seem to do anything at all… how have people configured it?

[EDIT] oooops I missed the “button_keys 0 0 0 0 13 14 0 0 0 0 0 0 0” line…[/EDIT]

Oh, also, does it auto update or something, or do I need to keep an eye out on updates and unzip them manually?

Thanks again!


I’m not sure if anyone else will want this, but I wrote a small script to add volume controls to PICO-8.
Here’s the code:
and a video of it running:


Ooh nice! Will it autorun or does the user have to execute each time? I don’t have a in the pico-8 dir…

[EDIT]…but, here it is: /home/cpi/apps/launcher/Menu/GameShell/

[EDIT2] Hmm… followed the instructions to a t, but it doesn’t work…

My reads:

SDL_VIDEODRIVER=x13 DISPLAY=:0 python /home/cpi/pico-8/
SDL_VIDEODRIVER=x11 DISPLAY=:0 /home/cpi/pico-8/pico8_dyn -splore -draw_rect 32,0,256,240

Have installed pyxhook, is in home/cpi/pico-8, but nothing happens with the vol keys.


Not only a selection of popular, you can also see the most recent published in some category.
The only thing that would not work at the moment is the search as it need a keyboard.