How to Add Games to EmulationStation: ROM Loading, Scraping, and Configuration Explained

You’ve just installed EmulationStation on your Raspberry Pi or PC. The menu is clean, the interface is responsive, and you’re ready to fill it with your game collection. Then you hit the first real obstacle: the games won’t show up. You’ve dropped ROM files into what you thought was the right folder, but EmulationStation displays nothing. Or worse—the games appear, but with generic icons and no metadata. You’re left staring at a folder called “snes” with an empty game list.

This is one of the most common friction points in retro gaming setup, and it typically comes from misunderstanding how EmulationStation actually organizes, reads, and displays games. It’s not magic—it’s a specific technical workflow with clear rules and logical requirements. But those rules aren’t obvious if you’re approaching it for the first time.

In this guide, I’m going to walk you through the actual mechanics of how EmulationStation discovers, loads, and displays ROM files. You’ll learn where files need to live, how metadata scraping works, what makes a valid game entry, and how to diagnose problems when your library refuses to populate. More importantly, you’ll understand the structure well enough to troubleshoot and customize your setup for exactly how you want to organize your collection.

Why EmulationStation Isn’t Finding Your Games

Before we talk about solutions, let’s clarify what’s actually happening under the hood. EmulationStation doesn’t scan randomly through your hard drive looking for ROM files the way Windows Media Player hunts for music. Instead, it uses a hierarchical, structured approach: it looks in specific directories for specific file types, parses metadata from external sources, and maintains an internal database of what it’s found.

If your games aren’t showing up, it’s almost always one of these reasons: ROMs are in the wrong folder, the emulator executable isn’t properly configured, the ROM file extensions don’t match what the system expects, or EmulationStation hasn’t been told to rescan the game list. Understanding this structure is the foundation for getting everything working reliably.

The Directory Structure: Where EmulationStation Expects to Find Games

EmulationStation uses a standardized folder hierarchy that you need to respect. The root directory is called the “ROM root” or “roms” directory—this is the parent folder containing all your organized game libraries. By default, on Raspberry Pi RetroPie installations, this is located at /home/pi/RetroPie/roms. On other systems, it might live in your home directory or a custom location you’ve specified during setup.

Inside this roms directory, you’ll find subdirectories named after specific systems. These names matter—they’re not arbitrary. A folder called “snes” tells EmulationStation to associate games in that folder with the Super Nintendo emulator. A folder called “nes” maps to the NES. A folder called “gameboy” maps to Game Boy emulators. EmulationStation has a hardcoded list of recognized system folder names, and if your folder doesn’t match one of those names exactly, it simply won’t be recognized.

Here’s the critical part: these system folder names are defined in EmulationStation’s configuration file, typically called es_systems.cfg. On RetroPie systems, this file is usually located at /etc/emulationstation/es_systems.cfg. Inside this XML file, you’ll find entries like this:

<system>
<name>snes</name>
<fullname>Super Nintendo Entertainment System</fullname>
<path>~/RetroPie/roms/snes</path>
<extension>.smc .fig .sfc .gd3 .swc .zip</extension>
<command>/opt/retropie/emulators/snes9x/snes9x %ROM%</command>
</system>

This tells EmulationStation: look in the snes folder, accept files with these specific extensions, and when launching a game, execute this emulator binary with the ROM file as a parameter. The %ROM% placeholder gets replaced with the full path to the selected game file.

The folder structure itself is simple but non-negotiable:

RetroPie/
├── roms/
│ ├── nes/
│ │ ├── Super_Mario_Bros.nes
│ │ └── Castlevania.nes
│ ├── snes/
│ │ ├── Super_Metroid.sfc
│ │ └── Chrono_Trigger.smc
│ └── gameboy/
│ ├── Tetris.gb
│ └── Pokemon_Red.gb

This structure is important for more than just organization—it’s how EmulationStation maps each ROM file to the correct emulator. When you try to launch a file from the snes folder, it automatically knows to use the SNES9x emulator, not the NES emulator.

File Extensions and Compression: What EmulationStation Actually Reads

Not all ROM files are created equal. Some are plain, uncompressed binary files. Others are compressed in ZIP archives. EmulationStation can handle both—but only if the extension is explicitly listed in the system configuration.

Let’s use the SNES as an example. Most SNES ROM files you’ll encounter have one of these extensions: .smc, .sfc, .fig, or .swc. These all represent the same underlying data—the actual SNES cartridge ROM dump—but with different header structures or no headers at all.

Why the different extensions? It’s historical. In the early days of ROM distribution, different tools created ROM backups with different file formats. A file with an SMC header includes 512 bytes of metadata at the start that describes the ROM. An SFC file typically has no header or a different header structure. Both contain the exact same game code, but they’re formatted differently. Modern emulators like SNES9x can usually detect and skip headers automatically, but the file extension tells the emulator to try to read the file in the first place.

ZIP archives are handled specially. If you have a file called Super_Metroid.zip containing an SNES ROM file inside it, EmulationStation can still launch it—the emulator knows how to extract the contents automatically. However, only the system configurations that explicitly list .zip in their extension field will attempt to launch ZIP files. Not all systems support this, and many advanced users compress their ROM files unnecessarily, adding a step of decompression that the emulator has to perform each time the game launches. If fast load times matter to you, uncompressed ROMs are typically faster, though the difference on modern hardware is usually negligible.

The key rule: if your file extension isn’t listed in the system’s configuration, EmulationStation won’t even attempt to read it. So if you have a file called Super_Mario_Bros.rom and the NES configuration only specifies .nes, .zip, and .7z, EmulationStation will silently ignore your file. No error message, no warning—it just won’t appear in the game list.

How EmulationStation Discovers Games: The Scanning Process

When you first launch EmulationStation or explicitly tell it to rescan the game list, it performs a specific sequence of operations:

1. Reads the system configuration. EmulationStation loads the es_systems.cfg file and builds a list of recognized systems with their ROM directories, valid extensions, and emulator commands.
2. Iterates through each system folder. For every system defined in the config, it checks if the corresponding ROM directory exists on the filesystem.
3. Lists all files in that directory. It reads the contents of, for example, ~/RetroPie/roms/snes.
4. Filters by extension. It only considers files whose extensions match the system configuration. A file called manual.txt or readme.pdf in the same folder is completely ignored.
5. Creates game entries. For each valid file found, EmulationStation creates an internal game entry with a display name (usually derived from the filename), the full file path, and a reference to which emulator to use.
6. Looks for metadata. EmulationStation checks for a local metadata file (more on this below) or marks the game as needing to be scraped.
7. Writes the game list. EmulationStation saves the discovered games to an internal database file, typically called gamelist.xml in each system’s ROM folder.

This is why a simple folder rescan can fix many problems—if you’ve added new ROM files to the correct folder after EmulationStation has already scanned it, those new files won’t appear until you explicitly rescan the collection.

Metadata, Scraping, and the Gamelist: Getting Artwork and Game Information

A game entry in EmulationStation consists of more than just a filename and an emulator. It also includes metadata: the full game title, a description, release year, developer, artwork (box art, screenshots, and promotional images), and more. This metadata is what makes the interface visually appealing and informative. Without it, you’re left with a plain list of filenames.

EmulationStation stores this metadata in a file called gamelist.xml. This is an XML-format database that lives in each system’s ROM folder. Here’s a simplified example of what it looks like:

<gameList>
<game>
<path>./Super_Metroid.sfc</path>
<name>Super Metroid</name>
<desc>Samus Aran returns to Planet Zebes...</desc>
<releasedate>19940418</releasedate>
<image>./media/images/Super_Metroid-image.png</image>
</game>
</gameList>

The path field points to the actual ROM file. The name field is what gets displayed in EmulationStation’s interface. The image field is a relative path to artwork stored alongside the gamelist.

So how do these images and descriptions get populated? There are two methods: manual entry and scraping.

Manual entry means you manually edit the gamelist.xml file or use EmulationStation’s built-in game editing interface to add information for each game. This is tedious if you have a large collection but gives you complete control over what information is displayed.

Scraping is the automated approach. EmulationStation (or a separate scraping tool) sends your ROM filenames to online databases like TheGamesDB or ScreenScraper, which return matching game information, artwork, and metadata. The scraper then writes this information into the gamelist.xml file and downloads the associated image files to a media folder.

The scraper doesn’t guess—it tries to match your filename against known game records. If you have a file called Super_Metroid.sfc, the scraper will search the database for “Super Metroid” and, if successful, return the official game information and box art. If the filename is obscure or doesn’t match the database format exactly, the scraper might fail to find a match, and you’ll need to manually correct it.

This is why filename consistency matters. A file named SMETROID.SFC is much less likely to scrape successfully than Super_Metroid.sfc. Modern scrapers are reasonably forgiving, but clean, readable filenames dramatically improve the scraping success rate.

On RetroPie systems, scraping is typically handled by the built-in Scraper tool, which is accessible from the main menu. There are also standalone scraping tools like external tools for managing ROM storage that offer more control and batch processing capabilities.

Emulator Configuration: The Critical Missing Link

Here’s where many people get stuck: you can have perfectly organized ROM files and valid metadata, but if the emulator isn’t properly configured, your games still won’t launch.

Remember that command field we saw earlier in the system configuration? That’s the actual command EmulationStation executes when you select a game. For SNES, it might be:

/opt/retropie/emulators/snes9x/snes9x %ROM%

This tells the system: “Run the snes9x program located at this path, and pass the selected ROM filename as a parameter.” If the snes9x executable doesn’t exist at that path—maybe it’s installed elsewhere, or maybe it’s not installed at all—the launch will fail.

On RetroPie systems, emulator paths are pre-configured for you if you’ve installed emulators through the RetroPie setup menu. But if you’re setting up EmulationStation manually on another system, or if you’ve installed emulators manually, you need to ensure these paths are correct.

To verify your emulator setup, you can navigate to the directory in your file system and check whether the executable exists. On Linux-based systems, you can also run the command directly from a terminal to see if it launches the emulator or produces an error message.

The %ROM% placeholder is literal—EmulationStation replaces it with the full path to the selected ROM file when the command is executed. Some emulators are picky about how ROM paths are passed (absolute vs. relative paths, quoted vs. unquoted), and occasionally you need to adjust the command string to match your emulator’s expectations.

Step-by-Step: Getting Games Into EmulationStation

Now let’s walk through the actual process of adding your ROM collection to EmulationStation, from folder organization through successful gameplay.

Step 1: Verify your ROM root directory

1. On a RetroPie system, open a terminal (or SSH if you’re accessing remotely) and navigate to your home directory.
2. List the contents: ls -la | grep RetroPie
3. If you see a RetroPie folder, that’s your ROM root. Navigate into it: cd ~/RetroPie
4. Check that a roms directory exists: ls -la roms
5. If the roms directory doesn’t exist, create it: mkdir -p roms
6. If you’re on a different system, verify where EmulationStation is configured to look for ROMs. This is typically in the EmulationStation configuration file, usually located at ~/.emulationstation/es_systems.cfg. Check the path entries in that file.

Step 2: Create system-specific subdirectories

1. Inside the roms directory, you need subdirectories for each system you want to emulate.
2. For a basic setup, you might create: mkdir -p roms/{nes,snes,gameboy,genesis,arcade}
3. Verify these exist: ls -la roms/ should show your new directories.
4. Make sure these directory names match exactly what’s defined in your es_systems.cfg file. If the config says snes but you created SNES, EmulationStation won’t find it (Linux is case-sensitive).

Step 3: Place ROM files in the correct folders

1. Copy or move your ROM files into the appropriate system folders. For example, NES ROMs go into the nes folder, SNES ROMs go into the snes folder.
2. Verify file extensions. If you have SNES ROMs with a .nes extension (which would be incorrect), rename them to .sfc or .smc.
3. Clean up unnecessary files. Remove non-ROM files like readme files, BIOS files (unless they’re required by the emulator and belong in a BIOS folder), or media files from the ROM directories themselves.
4. Example: cp ~/Downloads/mynes_roms/* ~/RetroPie/roms/nes/

Step 4: Verify emulator installation

1. Check that the emulators referenced in your es_systems.cfg are actually installed on your system.
2. On RetroPie, you can check via the setup menu. Navigate to Manage Packages → Manage Core Packages and verify that the emulators you need (SNES9x, Nestopia, Genesis Plus GX, etc.) are marked as installed.
3. On other systems, try running the emulator from the command line directly. For example: snes9x --help should either show help text or confirm the executable exists.
4. If an emulator isn’t installed, install it. On RetroPie, this is done through the setup script. On other systems, follow your emulator’s installation instructions.

Step 5: Force EmulationStation to rescan

1. Launch EmulationStation.
2. Navigate to the main menu (typically press ESC or the Select button).
3. Look for an option called “Scraper,” “Update Game List,” or “Rescan.” On RetroPie, this is usually under the main menu.
4. Select this option to force a rescan of all ROM directories. EmulationStation will now discover your ROM files.
5. Wait for the scan to complete. On systems with large ROM collections, this can take a minute or two.

Step 6: Scrape metadata (optional but recommended)

1. After scanning, your game list will show your ROMs with plain filenames but no artwork or descriptions.
2. To add artwork and information, use the Scraper tool. On RetroPie, go to Main Menu → Scraper.
3. You can scrape individual systems, all games, or just games missing metadata.
4. The scraper will attempt to match each filename against online databases and download artwork and information.
5. Scraping success depends on filename accuracy. If a file doesn’t match, the scraper will usually offer suggestions or let you manually select the correct game.
6. After scraping completes, reload EmulationStation to see the updated interface with artwork and game information.

Step 7: Test launching a game

1. In EmulationStation, navigate to a system folder (e.g., NES).
2. Select a game and press Enter (or the configured launch button).
3. The emulator should start and the game should launch. If it doesn’t, check the troubleshooting section below.
4. Test a game from each system you’ve configured to ensure emulators are working across the board.

Troubleshooting: Why Your Games Aren’t Showing Up or Launching

If you’ve followed the steps above and games still aren’t appearing, here’s how to diagnose the problem.

Games don’t appear in the list at all

Likely cause: ROM files are in the wrong folder, or the folder isn’t recognized by EmulationStation.

Diagnosis: Manually verify the folder structure matches your system configuration. Open a terminal and navigate to your ROM directories: cd ~/RetroPie/roms && ls -la. You should see subdirectories like nes, snes, etc. If the folder you created isn’t here, it hasn’t been created yet.

Solution: Create the missing folder. Verify the name matches exactly what’s in your es_systems.cfg (remember, Linux is case-sensitive).

Secondary cause: ROM files have incorrect extensions.

Diagnosis: List the files in one of your ROM folders: ls -la ~/RetroPie/roms/snes/. Check the file extensions. If you see files like game.zip but your system configuration doesn’t list .zip as a valid extension, those files won’t appear.

Solution: Rename files to use the correct extension, or update your system configuration to include the extensions you’re using. Commonly valid extensions for each system are listed at the beginning of each system’s configuration entry.

Games appear in the list, but won’t launch

Likely cause: The emulator path in your system configuration is incorrect.

Diagnosis: From a terminal, try running the emulator command manually. For SNES9x, this might be: /opt/retropie/emulators/snes9x/snes9x. If you get a “command not found” error, the path is wrong or the emulator isn’t installed.

Solution: Verify the correct path to your emulator. On RetroPie systems, emulators are typically installed in /opt/retropie/emulators/. List that directory to find the exact emulator name and path: ls -la /opt/retropie/emulators/. Update your es_systems.cfg with the correct path.

Secondary cause: The emulator isn’t installed at all.

Diagnosis: Check your RetroPie Manage Packages menu, or try running the emulator from the command line.

Solution: Install the emulator. On RetroPie, use the setup script. On other systems, follow the emulator’s installation instructions.

Games appear but are missing artwork or descriptions

Likely cause: The gamelist hasn’t been scraped yet, or the scraper couldn’t match your filenames.

Solution: Run the Scraper tool. If a filename doesn’t match, the scraper will offer suggestions. Select the correct match, and the metadata will be downloaded and stored in the gamelist.

Alternative: Rename ROM files to more standard, recognizable names. A file called sm.sfc is much less likely to scrape successfully than Super_Metroid.sfc. After renaming, rescan and re-scrape.

Some games scrape successfully, others don’t

Likely cause: Your filenames don’t match the database entries exactly, or the database doesn’t have an entry for that specific ROM release.

Solution: The Scraper tool will usually ask you to manually select the correct game if it finds multiple matches or no exact matches. Take the time to manually match games that don’t scrape automatically. For very obscure or region-specific releases, you might need to use alternative scrapers or enter metadata manually.

Advanced: Custom Emulator Configurations and Multiple Versions

Once you have the basics working, you might want to customize individual emulator behavior or use different emulators for the same system.

EmulationStation supports per-system emulator selection through configuration files. You can set default emulators, enable custom settings, and even chain multiple emulator options. However, these configurations are typically handled through RetroPie’s runcommand interface, which lets you choose which emulator to use when launching a game.

On RetroPie, when you launch a game, you might see a menu asking which emulator to use (if multiple are installed for that system). You can set a default and remember your choice, or select a different emulator each time. This is handled by a script, not directly by EmulationStation, but the integration is seamless.

If you’re manually editing system configuration files, be aware that some changes require EmulationStation to be restarted before they take effect. On RetroPie, you can edit the es_systems.cfg file directly, but the system will need to be rebooted or EmulationStation restarted for changes to be recognized.

For most users, the default emulator selections provided by RetroPie are excellent and require no customization. But power users can deeply customize which emulator is used for each system or even create custom emulator entries for specific game collections.

Optimizing Your ROM Organization for Long-Term Maintenance

Beyond just getting games to appear and launch, think about how you’ll organize your collection for maintainability and future expansion.

Filename consistency: Use a standard naming format across your entire collection. Something like Game_Name_-_Country_(Year).ext is clear and scrapes reliably. Avoid special characters that might cause issues on some filesystems. Spaces are fine, but avoid characters like *, ?, <, >, and |.

ROM compression: While ZIP files are supported, leaving ROMs uncompressed is generally faster and simpler. If you’re constrained by storage space, compression is worth considering, but modern drives are large enough that this is rarely necessary anymore. Only compress if storage is genuinely a limitation.

BIOS files: Some emulators require BIOS files to function. These are typically system ROMs from real consoles. Rather than storing them with your game ROMs, most systems have a dedicated BIOS folder. On RetroPie, this is usually ~/RetroPie/BIOS/. Keep BIOS files separate from game ROMs to avoid cluttering your game list.

Regular rescans: If you’re regularly adding new games to your collection, periodically rescan and re-scrape to keep your game list up to date. It only takes a minute or two and ensures new additions appear with full metadata.

Backup your gamelist: The gamelist.xml file in each system folder contains all your metadata and scraped information. If you ever need to reset EmulationStation or move your setup to a new system, keeping a backup of these files saves you from having to rescrape everything from scratch. You can simply copy the gamelist.xml (and the associated media folders) to your new setup.

When Manual Metadata Entry Makes Sense

Scrapers are fast and reasonably accurate, but sometimes you need to manually edit metadata. This might be for games that don’t exist in the scraper database, obscure regional releases, or ROM hacks and homebrew games that obviously won’t match any commercial database.

On RetroPie, you can edit individual game entries by navigating to a game and pressing Select (or the configured edit button). This opens an interface where you can change the display name, add a description, and even manually select artwork files.

For bulk manual editing, you can edit the gamelist.xml file directly in a text editor. The format is straightforward XML, and any text editor will work. However, be careful with the syntax—a misplaced tag can break the entire gamelist. Always keep a backup before making manual edits.

The reality is that for most collections, automated scraping handles 90%+ of your games without intervention. The remaining 10% might need manual attention, but that’s usually a one-time investment per game.

Final Thoughts: From Setup to Regular Use

Adding games to EmulationStation is straightforward once you understand the underlying structure. ROM files go in system-specific folders, emulators need to be installed and configured, and metadata comes from either scrapers or manual entry. There’s no magic—it’s just a logical workflow.

The most common mistake is skipping one of these steps or assuming EmulationStation knows where to find files when you haven’t explicitly told it. Take the time to verify each step: folders exist, ROM files are in the right place with correct extensions, emulators are installed, and the system configuration is accurate.

Once everything is set up, maintenance is minimal. New games can be added to the appropriate folders, rescanned, and scraped in a few minutes. EmulationStation’s strength is that it provides a unified, elegant interface for managing what would otherwise be a tedious collection of individual emulators and ROM files.

If you’re setting up a retro gaming collection for the first time and want to understand the broader context of emulation and game preservation, the complete guide to setting up a home retro arcade provides practical recommendations for building a full system. Similarly, understanding how to organize and store your actual ROM files is covered in detail in our guide to external storage for ROM collections.

The technical fundamentals of how EmulationStation works are sound and consistent. Once you’ve internalized them, you’ll be able to troubleshoot problems, customize configurations, and scale your collection as it grows. That’s the real power of understanding the system instead of just following a step-by-step checklist.