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. Instructions are included here for convenience.

There are two ways to install RetroPie with the current version of EmulationStation.

Download a pre-made image and flash your SD card.

Download the latest image from the RetroPie website.

Write it to your SD card using a tool like SD Formatter 4.0 or Win32 Disk Imager. Or dd , if you're a Linux guru.

The image should be pre-configured, pre-themed, and automatically start EmulationStation after booting. Use sudo raspi-config and choose to expand the root filesystem, so the image uses the entire SD card, then sudo reboot.

After that, all you need to do is add ROMs, either over SSH or a USB stick. See the RetroPie Wiki for more details.

Or, compile everything from source yourself.

This option will take the most time (up to 17-20 hours), but with leave you with the most up to date version of everything. You can limit how many emulators you install to save time.

First, download the latest Raspbian image from the Raspberry Pi website and write it to your SD card with one of the tools mentioned above.

Next, boot from your SD card and login with user pi and password raspberry. Next, type the following commands.

Make sure package sources are up to date

sudo apt-get update

Make sure git and dialog are installed

sudo apt-get install git dialog

Download the RetroPie-Setup script

git clone --depth=0

Run the script

chmod +x
sudo ./

Once in the installer, select 'SOURCE-BASED INSTALLATION' with the arrow keys and press enter. On the next screen, use the arrow keys and space bar to select/deselect which parts of RetroPie you would like to install. You can deselect any emulators you do not wish to use. Once you are finished, press enter and begin waiting.

Once the setup is complete, restart your Raspberry Pi with sudo reboot (to make sure firmware updates take effect).

EmulationStation should be pre-configured and pre-themed. All you need to do is add ROMs, either over SSH or a USB stick. See the RetroPie Wiki for more details.

Installing on Raspberry Pi (Stand-alone)

This is a guide for everything you need to install EmulationStation on a fresh Raspbian Wheezy install.

EmulationStation requires SDL2, which isn't in the Raspbian repositories, so this guide will also show you how to compile and install SDL2.

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 SDL2

sudo apt-get install -y libudev-dev libasound2-dev libdbus-1-dev libraspberrypi0 libraspberrypi-bin libraspberrypi-dev

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 g++-4.7

NOTE: if you don't install libudev-dev before building SDL2, the keyboard will mysteriously not work in EmulationStation.

Compile and install SDL2

tar xvfz SDL2-2.0.1.tar.gz
rm SDL2-2.0.1.tar.gz
pushd SDL2-2.0.1
# "--disable-video-opengl" is used to disable the software implementation of desktop OpenGL on the Pi
# "--host=*" is used to force the Raspberry Pi host. See issue #395 on GitHub for details on why.
./configure --disable-video-opengl --host=arm-raspberry-linux-gnueabihf
sudo make install

If you like, you can delete the SDL2-2.0.1 folder now (the library has been installed):

rm -rf SDL2-2.0.1

Compile and install EmulationStation

git clone
cd EmulationStation
git checkout unstable
# On the RPi 2, you may need to add '-DFREETYPE_INCLUDE_DIRS=/usr/include/freetype2/' before the period.
# See issue #384 on GitHub for details.
cmake -DCMAKE_CXX_COMPILER=g++-4.7 .

This will take a very, very long time (multiple hours).

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 this folder with:


Reset GPU RAM to normal values and reboot

sudo nano /boot/config.txt
# change "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.