Latest Posts

Building Widelands

This page is about building Widelands for various operating systems. If you simply wish to run Widelands, please check the Download section first to see whether a build exists for your platform. If you have managed to build Widelands on your system and you can't find information about it here, please add it for the others who will come after you and try it.


Widelands currently depends on the following libraries, make sure they all are installed and in the search path of your compiler. We currently support compilation with GCC >= 5.4 or Clang/LLVM >= 3.4, though it might work with other compilers too.

Additional Tools

If you are a developer, you might (optionally!) make use of the following software:

  • ctags
  • optipng Used to make PNG images more compact. You most certainly don’t need this; compactification is a once-a-year, one-person-only job. If you don’t know already that you will be doing it, forget about it.
  • Doxygen Used to generate source code documentation.
  • gdb GNU debugger for analyzing crashes

Installing dependencies

In order to build successfully, Widelands require the libraries listed above to be installed on your system. How these packages are installed vary from system to system, in addition to some libraries being required only for specific versions of Widelands, so we ship a script that installs all needed dependencies automatically on most common systems. Simply run in the top-level of the downloaded source code directory:


Building Widelands with compile script (fastest way)

First of all, make sure that all required packages are installed (see previous step). As soon as you are ready with this step,

  • Download the latest build or clone the repository, then switch to the desired branch. Instructions for this are on our Gitprimer page.
  • Display compile options
    • -h
  • Compile Widelands, for example::
    • $ ./ -r for a release build, or $ ./ -a for a debug build without AddressSanitizer
  • To run Widelands after compilation or to run it again later on (in last case make sure you are in Widelands directory (cd widelands)):
    • $ ./widelands

If you use git versions, you are able to update Widelands via running ./ (again make sure you are in the Widelands directory)

Rebuilding in case of changes

If you want to rebuild Widelands with different compile options (e.g. change from release build to debug or vice versa), or with updated build environment or dependencies, you are strongly advised to remove the entire build subdirectory first to ensure a clean build.

Building with CMake manually (advanced)

Building with CMake allows you greater control and more options when building. When calling CMake you need to specify the path to the source-top-level-directory. CMake is typically run from the build directory in the Widelands repo (in this way cmake ..), but you can also create your own build directory somewhere else, e.g. cd ~/some-other-build-directory && cmake ~/widelands.

CMake options

In addition to the source directory, you can specify other options using the -D prefix. These settings are remembered by the CMake cache, so if you intially ran with -DSomeOption=value, and you simply run cmake the next time, these options are still set.

The available options are documented in our GitHub Readme.


If you configured CMake with Ninja, replace the make command with ninja (or ninja-build).

Make targets are documented in our GitHub repository


Check out the latest version of the source code and switch to the desired branch. See Gitprimer.

Using CMake

  • Enter the build directory
    • $ cd build
  • Run CMake with your choice of options. The example will build a Debug build without AddressSanitizer, portable, with a custom install destination
    • $ cmake -DCMAKE_INSTALL_PREFIX=~/widelands-cmake-install -DWL_PORTABLE=true -DOPTION_ASAN=OFF -DCMAKE_BUILD_TYPE=Debug ..
    • if you want to have a different install directory for "make install" instead of /usr/local

Using make

Once Cmake has finished, run make to start compiling.

  • $ make -j3
    • -j3 tells make to run 3 concurrent tasks, which is recommended for Dual-Core CPUs. Basic rule is -j(number of cores + 1) as recommendation, but beware, gcc takes lots of RAM. If you wish to install the newly build version to your system, run:
  • $ make install -j3
    • this compiles the sources and then installs in either /usr/local (which you need root privileges for), or in the directory specified with -DCMAKE_INSTALL_PREFIX
    • make install includes make, so "make install" is basically the same like "make && make install"

Running freshly built Widelands

  • if you did just "make"
    • From any directory (which is not a different widelands data directory)
    • ./build-cmake/src/widelands
    • ATTENTION: This is not recommended, since it will be missing some files (locale, consolidated pics...). Use "make install" instead.
  • if you did "make install" and were root
    • $ /usr/local/bin/widelands
  • if you were not root, used "make install" and specified "-DCMAKE_INSTALL_PREFIX" as above
    • ~/widelands-cmake-install/widelands


You may consider using separate build directories if you want to have both a release and a debug build. Otherwise you are strongly advised to remove the entire content of the build directory when you change compile options, as this is the surest and most effective way of ensuring a clean build.

You also need to do this if you update your build environment or some dependencies.

Failing to clean up properly in these cases is known to cause subtle bugs.

Building under Windows

You have the option to use Min-GW, Inno-Setup or Visual Studio for building Widelands on Windows. While the Min-GW setup is used during continuous integration, the Visual Studio environment enables easy access to debug utilities.

Building in Visual Studio

Please visit Building Widelands in Visual Studio

Building under MinGW

Please visit Buildingwidelandsunderwindowsnew

Building under Innosetup

Since Build10 we support an Innosetup file, which can be used for compiling an installer (like the official Widelands installer). Innosetup can be downloaded from

If you’ve installed InnoSetup, you just need to open [Widelands]/build/win32/Widelands.iss. You might change few settings or directly start packing/compiling the setup.


Please check if all needed *.dll-files are in [Widelands]-directory during Setup packing/compile. Else your setup might be useless :-?

Building under macOS

You can find further information under Building Widelands on Macos. We recommend that you use the method explained there, since these build instructions are most current.

Tagged with: Development, help