Table of Contents


  1. Install the game(s), the bg2 demo or use the included minimal dataset test

Installing gemrb

Everything can be fetched through our download page.

The use of the most recent release is strongly suggested! Nobody cares about old bugs.

Specific instructions

Automatic builds are pretty stable, so if you only have access to older versions for whatever reason, do try a buildbot build! Some games are unplayable in older versions …

Compile it yourself


Make sure you have SDL, python, zlib and a compiler installed (with all their header/devel packages if they exist). You will also need either cmake (recommended) or autotools (unmaintained).

Full list: Python, SDL, zlib, OpenAL or SDL_Mixer (if you want sound), libPNG (optional), Freetype (if you want TTF fonts), iconv (if you want TTF fonts while using non-unicode dialog.tlk)

When not using an IDE to build, make will be required. Also, on Windows a Cygwin environment can be used instead of MSVC.

Getting the sources

First you'll need to get the source. Either in the form of a release tarball or the latest source from GIT (preferred).

The advantage of the development tree is that you always have the most updated version, with bugfixes and features added after release. Of course, you may also get extra bugs, while the changes are being polished.

This probably gets more complicated if you're on Windows because, but you can try running the builds from here.

Source tarball

Download the source tarball from the project page.

Latest tree from GIT

Create a (readonly) checkout of gemrb in the current dir with:

git clone git://


If you have the tarball, extract it. The rest of the instructions are the same as for building from Git. First move to the source directory then run the following:

mkdir build
cd build
cmake ..
make -j2

By default, GemRB is installed into /usr/local (“fhs”). You can pass -DLAYOUT with “home” or “opt” to change the general layout and -DPREFIX to change the install path prefix. Pass -DCMAKE_BUILD_TYPE=Debug to cmake if you want to create a debug build.

If you're using one of the available project files, just build as usual.


For a self-compiled gemrb, installation is not necessary and you just need to use a different configuration file. See The minimal dataset for a good starting point.

Otherwise run the customary: make install

Optional script to automate compiling and installing gemrb from git

If you wish to install dependencies, compile gemrb from git, and install it all in one go, please see the script at this github repository. Dependencies will only be installed if you are on Ubuntu, Mint, or Debian. Full instructions for its usage are at that site.

Installing the games

After you have the games, you can also install mods. Most WeiDU mods will work out of the box, but some may have problems due to case sensitivity. Report such problems to the mod's authors.

Existing installations

If you already have a game installed somewhere, even if it is on another OS, just make sure that that filesystem is mounted (writable or you won't be able to save!) and point gemrb to the relevant directory (set GamePath in the configuration file).


Just run the normal Setup.exe and follow through to the end. You can complicate the matter by using packed ISO images as described here. Remember to do a full install.


See unshield-bg2, unshield-bg1 (similar for the others, just not documented). You can get it here.

Baldur's Gate 2 Demo

There is a free bg2 demo available. You can get it from FilePlanet or elsewhere on the net.

Install it like it was a game from the previous sections.

Python installer

You can also try NJW's GemRB Installer.

Configuring gemrb


  1. Copy one of the GemRB.cfg samples and rename it to <game_name>.cfg . You can name configuration files arbitrarily, but this way makes the most sense if you'll be running multiple games.
  2. Edit GemRB.cfg. The only two things that always need to be changed is the path to the game's data files (GamePath, CDx) and the desired game (GameType). It is crucial you get this right. 2)

Setting the paths can be tricky, so carefully read the errors that gemrb prints to the output before exiting. See this video (linux) for a walktrough on how to fix the encountered problems and set up the paths properly.


Use the external launcher.

Test run

You will know gemrb is working perfectly once you can see the main game screen. If that doesn't happen, check the console for errors and fix the configuration file as needed. Usually some path is set wrong.

The minimal dataset

Since 0.6.1 GemRB comes with a minimal dataset, that can be used to check if gemrb is configured correctly right out of the box.

If you installed gemrb, try the included fhs.cfg:

gemrb -c /usr/share/gemrb/minimal/fhs.cfg

If you don't want to install, you can just run the sample config from the build directory as-is:

gemrb/gemrb -c ../gemrb/GemRB.cfg.noinstall.sample

It will exit as soon as it loads the Start script. That is the expected behaviour.

iPhone/iPad/iPod Touch
note that on Unix-like systems, you must not escape the spaces in the various paths