Using Scraper on RetroPie

RetroPie is a fun little arcade system that runs on Raspberry Pi. It includes Emulation Station, which allows the user to select games using a USB game pad or joystick instead of a keyboard.

One of Emulation Station’s features is a scraper, which analyzes your library of game ROMs and tries to download the appropriate artwork and game metadata from online databases. If successful, when you browse your library you will be presented with nice art and game descriptions.

I was excited to try the scraper, but ultimately found Emulation Station’s scraper to be very hit-or-miss.

Dozens of online forums and articles laud Steven Selph’s Scraper as being faster and more thorough, so I decided to give it a try. I was able to get Scraper installed rather quickly using the official RetroPie instructions for installing Scraper, but they unfortunately don’t give you much guidance beyond installation.

I rolled up my sleeves and spent a few hours tinkering. Here are my notes.

My first obstacle was how to access Scraper after installation. Seems silly in retrospect, but this took me quite some time to figure out.

Quit Emulation Station (F4 on your keyboard). You will be taken to the RetroPie command line (shell).

Note for advanced users: You can also run commands from an external computer if you have enabled SSH in RetroPie. I used SSH for most of the tasks detailed below; it was especially handy to have SFTP enabled for managing files. (video demonstration).

Using the command line, launch the RetroPie setup script:

sudo ./RetroPie-Setup/

If you’re unfamiliar with the command line, an .sh file is a shell script. In this scenario, RetroPie-Setup is the folder containing the script, and is the name of the script. Placing ./ in front of the path to the script tells the system to run the script. To run the script as an administrator, begin the line with sudo (“superuser do“).

The line above is equivalent to

cd RetroPie-Setup
sudo ./

This will bring you to the RetroPie setup menu.

RetroPie setup menu

Go to “Configuration / tools”. You will be presented with a menu of options. Scraper will be listed near the bottom:

RetroPie configuration menu

Select Scraper and hit OK. You will be presented with the Scraper menu.

Scraper menu

I changed a few options and then let it “Scrape all systems”. It worked pretty well, but there was one thing that bugged me: the artwork Scraper grabbed was usually comprised of old posters or cabinet art, which often looked nothing like the game itself. I just wanted to see snapshots from within the game.

Turns out if you use Scraper on non-RetroPie systems, you have the option to specify a preference via command line flags. For example, you can specify an order of preference, with the options of snapshots, boxart, fanart, banner, and logo.

I tried for quite some time to run Scraper via command line in RetroPie, using the flags specified on the Scraper site, but I often encountered errors about specific flags not being supported. The only method that worked consistently was launching Scraper as I described above. But the option to specify a preference for image type is not built into the menu. Turns out this is a known limitation.

But where there is a will, there is a way. I looked at the contents of the file, and it was pretty trivial to add the missing flags directly to the file using a text editor.

The Scraper script file is located at


When accessing the folder using an SFTP app, it looks like this:

Scraper folder in SFTP app


I right-clicked in my SFTP app of choice and opened it using a text editor.

Line 82 had  params+=(-skip_check), so I added my own line directly underneath it:

params+=(-console_img "s,b,3b,l,f")

I am telling Scraper to get images for console games in this order of priority: snapshots, box art, 3D box art, logos, and fan art.

But my primary focus is arcade games, not console games; arcade games use a different flag for artwork. Looking further down the file, I noticed the line I wanted was 114. It already specified an order of priority for arcade games. I edited it to use my preferred order of priority: snapshots, marquees, then title.

[[ "$system" =~ ^mame-|arcade|fba|neogeo ]] && params+=(-mame -mame_img s,m,t)

I saved the file, closed it, then re-ran Scraper using the steps listed above. To my surprise, I didn’t see any significant changes to my artwork. Turns out the old artwork was still there, and Scraper only looks for art if no art exists. I needed to delete the old art first!

According to the file, the images are stored in $home/.emulationstation/downloaded_images/$system. For arcade games, this translates to  .emulationstation/downloaded_images/arcade.

Using the command line, I navigated to the parent folder:

cd .emulationstation/downloaded_images/

Then I removed the entire arcade folder:

sudo rm -r arcade

Warning, the sudo rm command is dangerous, it will delete whatever you specify. Be careful not to enter any typos.

When re-running Scraper, the snapshots downloaded as intended, and game menu in Emulation Station now displays the snapshots instead of old posters.

Hat tip to all of the open-source developers and others who created the tools and documentation that helped me sort this out.