Installing EmulationStation

Configuring EmulationStation

Installing on Windows

Download and run the installer.

Configure EmulationStation.

I wish every section was this short.

NOTE: if you choose to use the ZIP file instead, you must also install the MSVC2013 x86 redistributable.

Installing on Debian

You can either install a stable version of EmulationStation from a pre-made package, or compile the bleeding edge developer version.

Install the latest stable package.

Download and install the Debian package, either 32-bit or 64-bit.

Configure EmulationStation.

Or, compile the latest version yourself.

Make sure everything is up to date

sudo apt-get update
sudo apt-get upgrade

Install dependencies

sudo apt-get install -y libsdl2-dev libboost-system-dev libboost-filesystem-dev libboost-date-time-dev libboost-locale-dev libfreeimage-dev libfreetype6-dev libeigen3-dev libcurl4-openssl-dev libasound2-dev libgl1-mesa-dev build-essential cmake git

Download the latest source

git clone

Compile and install it

cd EmulationStation
git checkout unstable
cmake .
sudo make install

Installing on Raspberry Pi (RetroPie)

The RetroPie Project provides an easy way to install over 30 different emulators on the Raspberry Pi, using EmulationStation as a front-end. This is one of the easiest ways to get your Raspberry Pi ready for some retro gaming goodness.

NOTE: RetroPie is not a part of EmulationStation. If you have problems with it, report them on the RetroPie GitHub issues page. EmulationStation is only the front-end. Furthermore, the version of EmulationStation provided by RetroPie is a fork adding some RetroPie-specific customizations and features.

Installing on Raspberry Pi (Stand-alone)

This is a guide for everything you need to install EmulationStation on a fresh Raspbian Stretch install. All the dependencies are in the Raspbian apt repositories.

Make sure everything is up to date

sudo apt-get update
sudo apt-get upgrade
sudo rpi-update

Set the minimum amount of RAM to the GPU

sudo nano /boot/config.txt
# add or replace "gpu_mem = 32"
# if you skip this step, you will probably get "out of memory" errors when compiling

Reboot to apply GPU RAM changes and make sure you're using the newest firmware

sudo reboot

Install dependencies for EmulationStation

sudo apt-get install -y libboost-system-dev libboost-filesystem-dev libboost-date-time-dev libboost-locale-dev libfreeimage-dev libfreetype6-dev libeigen3-dev libcurl4-openssl-dev libasound2-dev cmake libsdl2-dev

Compile and install EmulationStation

git clone
cd EmulationStation
mkdir build
cd build

# On the RPi 2, you may need to add '-DFREETYPE_INCLUDE_DIRS=/usr/include/freetype2/'.
# See issue #384 on GitHub for details.
cmake ..

# you can add -j2 here to use 2 threads for compiling in parallel (depending on how many cores/how much memory your RPi has)
make -j2

This will take a long time.

If you want to install emulationstation to /usr/local/bin/emulationstation, which will let you just type 'emulationstation' to run it, you can do:

sudo make install

NOTE: This will conflict with RetroPie, which installs a bash script to /usr/bin/emulationstation.

Otherwise, you can run the binary from the root of the EmulationStation folder:


Reset GPU RAM to normal values and reboot

sudo nano /boot/config.txt
# change/add "gpu_mem = 32" to "gpu_mem = 128" or "gpu_mem = 256", depending on your Pi model
sudo reboot

Configure EmulationStation and install some themes.

Configuring EmulationStation

WARNING: Do not edit configuration files while EmulationStation is running. This has been known to cause strange side effects, like overwritten files and melting the polar ice caps.

If you are using a pre-configured distribution like RetroPie, you can probably skip this section.

You might want to read the file as well as this document.

The .emulationstation Folder

EmulationStation stores all of its configuration files relative to some "home folder." Every EmulationStation configuration file goes in a .emulationstation folder inside of this "home folder."

I occasionally refer to this path as ~/.emulationstation . Just mentally replace the ~ with your platform's home folder.


On Windows, the "home folder" is set by the %HOMEPATH% environment variable. To see where that actually is, just type it into the Windows Explorer window and press enter:




So, the complete path to the .emulationstation folder is %HOMEPATH%\.emulationstation .


On Linx, this is equivalent to the $HOME environment variable. This is where your terminal and file browser should start.

So, the complete path to the .emulationstation folder is $HOME/.emulationstation .

NOTE: On Linux, files and folders that start with a . are "hidden folders," so the .emulationstation folder may not appear. If you are using the terminal, you can use ls -a to list all files in a directory, including hidden ones. If you are using a graphical interface, there should be an option to show hidden files and folders.

The es_systems.cfg File

This is the main configuration file for EmulationStation. It is located at ~/.emulationstation/es_systems.cfg . It is an XML document that defines a list of systems . A system contains the minimum information required to find your games and start them.

Here is an example, with comments:

<!-- This is the EmulationStation Systems configuration file. All systems must be contained within the <systemList> tag.-->

<!-- Here's an example system to get you started. -->

<!-- A short identifier for the system. Used in some folder structures and error messages. -->

<!-- A "pretty" name, displayed in the menus and such. This tag is optional. -->
<fullname>Super Nintendo Entertainment System</fullname>

<!-- The path to the top-most folder to start searching for games in. If the first character is '~', it will be expanded to the home folder. All subdirectories will be included. You can use forward slashes for any platform and backslashes on Windows. -->

<!-- A list of extensions to search for, delimited by commas or spaces. You MUST include the period at the start of the extension! It's also case sensitive. -->
<extension>.smc .sfc .SMC .SFC</extension>

<!-- This is the shell command that is executed to run a game. A few special tags are replaced if found in a command, like %ROM%. This example would run the shell command "snesemulator /home/user/roms/snes/Super\ Mario\ World.sfc".
<command>snesemulator %ROM%</command>

<!-- The platform(s) to use when scraping (download box art and such). You can see the full list of accepted platforms below. Everything should be lowercase. This is only *only* used to give more accurate search results, so this tag is optional. You can use multiple platforms, delimited by commas or spaces.  For example: "genesis, megadrive". -->

<!-- This is the theme to load from the current theme set. This tag is also optional; if not set, it will default to the value of <name>. It is recommended that you use a name from the "Recommended Theme Names" list below to make installing themes as painless as possible.-->



Notice all <system> s are listed inside of one <systemList> tag.

If you want to add another system, just add it like so:

<!-- System 1 -->

<!-- System 2 -->

<!-- And so on... -->

Systems are displayed in the order they are defined.

NOTE: If a system does not have at least one game present (that matches the extension list), it will not be displayed.
If no systems have games present, you will get an "invalid configuration" error!

Recommended Theme Names

EmulationStation will not restrict the names you pick for themes. However, in the interest of keeping installing themes a simple drag-and-drop process for everyone's setup, please use one of the following as your system's theme name:

NOTE: These are case sensitive on Linux.


(if it's not here, you are free to make something up, since a theme probably doesn't exist for it yet)

Platform Names

This is the list of valid platforms you can in a <platform> tag. The platform is used when scraping to provide more accurate results. You can use more than one platform.

NOTE: These are case sensitive.

  • 3do
  • amiga
  • amstradcpc
  • apple2
  • arcade
  • atari800
  • atari2600
  • atari5200
  • atari7800
  • atarilynx
  • atarist
  • atarijaguar
  • atarijaguarcd
  • atarixe
  • colecovision
  • c64 - commodore 64
  • intellivision
  • macintosh
  • xbox
  • xbox360
  • msx
  • neogeo
  • ngp - neo geo pocket
  • ngpc - neo geo pocket color
  • n3ds - nintendo 3DS
  • n64 - nintendo 64
  • nds - nintendo DS
  • nes - nintendo entertainment system
  • gb - game boy
  • gba - game boy advance
  • gbc - game boy color
  • gc - gamecube
  • wii
  • wiiu
  • pc
  • sega32x
  • segacd
  • dreamcast
  • gamegear
  • genesis - sega genesis
  • mastersystem - sega master system
  • megadrive - sega megadrive
  • saturn - sega saturn
  • psx
  • ps2
  • ps3
  • ps4
  • psvita
  • psp - playstation portable
  • snes - super nintendo entertainment system
  • pcengine - turbografx-16/pcengine
  • wonderswan
  • wonderswancolor
  • zxspectrum
  • ignore - do not allow scraping for this system; will remove this system from the scraping list and remove the "scrape" button in the metadata editor.

(if you suspect this is not up to date, check src/PlatformId.cpp )

Launch Commands

Launch commands depend on what emulator you want to use.

95% of the time, /path/to/emulator %ROM% or C:\path\to\emulator.exe "%ROM_RAW%" works.

If you're using MAME, /path/to/mame %BASENAME% should do the trick.

The following strings are replaced in your launch command:

Installing Themes

If you used the Windows installer or Debian package, a set of default themes should already be installed (to ~/.emulationstation/themes on Windows and /etc/emulationstation/themes on Linux).

As long as you used a name from the list above, you only need to download and extract the theme set to ~/.emulationstation/themes . If the themes folder doesn't already exist, just create it.

After that, select the new theme set in MENU -> UI SETTINGS -> THEME SET , like so:


That's it!

There's no dedicated Themes page on the website yet, but the official theme can be downloaded here.