Installing Freeciv21

The developers of Freeciv21 provide pre-compiled binaries and installation packages for tagged releases. They can be found on the LongTurn GitHub Repository for Freeciv21 at The LongTurn community provides binary packages for Debian based Linux distros (Debian, Ubuntu, Mint, etc.), Microsoft Windows® (32 and 64-bit), and Apple macOS®. If you are an Arch Linux user, you can find Freeciv21 in the AUR at

For more information on using the Windows Installer package, you can read about it at Windows Installation.

To install the Debian package, you will use the apt command with elevated privileges like this:

$ sudo apt install ./freeciv21_*_amd64.deb

If you want to get code that is closer to the master branch, you will want to compile the code yourself. Continue reading for instructions.

General Prerequisites to Compile Freeciv21

Freeciv21 has a number of prerequisites. Note, that apart from the first prerequisite, the Freeciv21 configuration process is smart enough to work out whether your system is suitable. If in doubt, just try it.

An operating system that support Qt

Any modern operating system that supports Qt 5.12+ is required. As of this writing this is Linux, Microsoft Windows® and Apple macOS®.

Linux Distributions:

  • Arch

  • CentOS 8+

  • Debian 11+ (Bullseye)®

  • Fedora 28+

  • Gentoo

  • KDE Neon

  • Manjaro

  • Mint 20+ or Mint Debian Edition (set to Bullseye)

  • openSUSE 15.2+

  • Slackware

  • Ubuntu 20.04 LTS+


The above list of Linux distributions is, of course, not exhaustive. The Freeciv21 Community has simply listed the mainline, well supported, distributions here. The code repository has Continuous Integration enabled and all code commits pass through Ubuntu, macOS and Windows for testing. It is assumed that the user is keeping his/her computer OS up to date. Support by the community for these distributions will be better than for some of the others out there, so keep that in mind if you are not an experienced Linux user.


The following instructions on this page are for Linux, MSYS2 and macOS environments. You will need to install MSYS2 first before continuing here if using MSYS2 on Windows. However, you can also compile on Windows with Microsoft Visual Studio. The Visual Studio instructions are self contained. No need to return to this page after following the installation instructions.

A C and C++ compiler

Freeciv21 is written in very portable C and C++. Both 32 and 64-bit machines are supported. You cannot use a “K&R C” compiler. The C++ compiler must support C++ 17.

Development of Freeciv21 is primarily done with gcc, the GNU project’s excellent C and C++ compiler. For complete cross-platform support the LongTurn community uses the LLVM project’s clang-cl compiler, which is supported on Linux, Windows and macOS.

The Cmake program

Freeciv21 developers generally use cmake, the Kitware make program. You can check if you have cmake installed on your system by typing the following command. The output should include “Kitware cmake” somewhere and the version should be >=3.12.

$ cmake --version
The Ninja cmake build program

Freeciv21 uses the ninja build tool. You can check if you have ninja installed on your system by typing the following command. The output should include ninja version >=1.10.

$ ninja --version
GNU Libtool

GNU Libtool is a generic library support script that hides the complexity of using shared libraries behind a consistent, portable interface. Freeciv21 requires version 2.2 or better.


SQLite is a C-language library that implements a small, fast, self-contained, high-reliability, full-featured, SQL database engine. SQLite is the most used database engine in the world. SQLite is built into all mobile phones and most computers and comes bundled inside countless other applications that people use every day. Freeciv21 requires version 3.

GNU Gettext

GNU Gettext is used for Internationalization support. Freeciv21 requires version 0.15 or better. The xgettext program is required to create the *.gmo files which are not included in the git tree.


Lua is a powerful, efficient, lightweight, embedable scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description. Exact version 5.3 is preferred.

KF 5 Archive Library

KArchive provides classes for easy reading, creation and manipulation of “archive” formats like ZIP and TAR.


SDL_mixer is a sample multi-channel audio mixer library.


Freeciv21 requires version 3 of Python

Prerequisites for the Client and Tools

The Freeciv21 project maintains a single Qt based client.

C++ compiler.

The client is written in C++, so you need an appropriate compiler. In Freeciv21 development, g++ has been used as well as tests against LLVM’s compiler (clang++)

QT Libraries

Freeciv21 uses the Qt libraries, specifically Qt5Core, Qt5Gui, Qt5Network, Qt5Svg, and Qt5Widgets libraries and headers.

At least version 5.12 is required.

Installing Package Dependencies

See the Debian Linux Packages section below on the steps to install the components for Debian Linux and its variants.

See the macOS Packages section below on the steps to install the components for Apple macOS.

If you are running Windows and want to use the MSYS2 environment and not set it up yet, then do so now, before continuing.

Lastly, if you are running Windows and want to use Visual Studio, you can follow the Microsoft Visual Studio instructions. The Visual Studio instructions are self contained. You do not neet to return here in that case.

Debian Linux Packages

Below are all the command line steps needed to start with a fresh install of Debian or its variants (e.g. Ubuntu, Linux Mint) to install Freeciv21.

Start with ensuring you have a source repository (deb-src) turned on in apt sources and then run the following commands:

$ sudo apt update

$ sudo apt install git \
   cmake \
   ninja-build \
   python3 \
   python3-pip \
   qtbase5-dev \
   libqt5svg5-dev \
   libkf5archive-dev \
   liblua5.3-dev \
   libmagickwand-dev \
   libsdl2-mixer-dev \
   libunwind-dev \
   libdw-dev \
   python3-sphinx \

At this point, follow the steps in Obtaining the Source Code section below.

macOS Packages

Below are all the command line steps needed to start with a fresh install of macOS.

$ brew update

$ brew install \
    cmake \
    ninja \
    python3 \
    gettext \
    brew link gettext --force

$ export VCPKG_ROOT="$HOME/vcpkg"

Obtaining the Source Code

In order to compile Freeciv21, you need a local copy of the source code. You can download a saved version in an archive file (.tar.gz or .zip) of the code from the project releases page at Alternately you can get the latest from the master branch with the git program with this command:

$ git clone


Configuring Freeciv21 for compilation requires the use of the cmake program.

On Debian Linux, to build with defaults enter the following command from the freeciv21 directory. Continue reading in the Other CMake Notes section below for more notes about other command line options you can give cmake.

$ cmake . -B build -G Ninja

On macOS, you need to use a preset that is defined in the CMakePresets.json file. When complete you can go to the Compiling/Building section below to continue.

$ cmake --preset fullrelease-macos -S . -B build


The first time you run the this command, cmake invoke the vcpkg installation process to download and compile all of the project dependencies listed in the manifest file: vcpkg.json. This will take a very long time. On a fast computer with a good Internet connection it will take at least 3 hours to complete. Everything will be downloaded and compiled into the $HOME/vcpkg directory. Binaries for the packages will be copied into the ./build/ directory inside of the main Freeciv21 directory and reused for subsequent builds.

Other CMake Notes

To customize the compile, cmake requires the use of command line parameters. cmake calls them directives and they start with -D. The defaults are marked with bold text.




Enables all the tools with one parameter (Ruledit, FCMP, Ruleup, and Manual)


Enables the server. Should typically set to ON to be able to play AI games


Enables Native Language Support


Enables the Freeciv21 Manual application


Enables the Qt client. Should typically set to ON unless you only want the server


Enables the command line version of the Freeciv21 Modpack Installer


Enables the Qt version of the Freeciv21 Modpack Installer (recommended)


Enables the Ruleset Editor


Enables the Ruleset upgrade tool


Changes the Build Type. Most people will pick Release


Allows an alternative install path. Default is /usr/local/freeciv21

For more information on other cmake directives see

Once the command line directives are determined, the appropriate command looks like this:

$ cmake . -B build -G Ninja \

A very common Debian Linux configuration command looks like this:

$ cmake . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=$PWD/build/install


Once the build files have been written, then compile with this command:

$ cmake --build build


Once the compilation is complete, install the game with this command.

$ cmake --build build --target install


If you did not change the default install prefix, you will need to elevate privileges with sudo.


If you want to enable menu integration for the installed copy of Freeciv21, you will want to copy the .desktop files in $CMAKE_INSTALL_PREFIX/share/applications to $HOME/.local/share/applications.

This is only necessary if you change the installation prefix. If you do not and use elevated privileges, then the files get copied to the system default location.

At this point, the compilation and installation process is complete. The following sections document other aspects of the packaging and documentation generation process.

Debian and Windows Package Notes

Operating System native packages can be generated for Debian and Windows based systems.


Assuming you have obtained the source code and installed the package dependencies in the sections above, follow these steps to generate the Debian package:

$ rm -Rf build

$ cmake . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/usr

$ cmake --build build --target package

When the last command is finished running, you will find a .deb installer in build/Linux-$arch

Microsoft Windows

There are two platforms available for installing Freeciv21 on Windows: MSYS2 and Visual Studio. The package target is only supported on MSYS2 due to licensing constraints.

Once your MSYS2 environment is ready, start with Obtaining the Source Code above. Instead of installing, use this command to create the Windows Installer package:

$ cmake --build build --target package

When the command is finished running, you will find an installer in build/Windows-$arch

Documentation Build Notes

Freeciv21 uses python3-sphynx and to generate the well formatted HTML documentation that you are reading right now. To generate a local copy of the documentation from the docs directory you need two dependencies and a special build target.

The Sphinx Build Program

The sphinx-build program is used to generate the documentation from reStructuredText files (*.rst).

ReadTheDocs Theme

Freeciv21 uses the Read The Docs (RTD) theme for the general look and feel of the documentation.

If you are running Debian Linux, the base program is installed by the instructions in the Debian Linux Packages section above. The documentation is not built by default from the steps in Compiling/Building above. To generate a local copy of the documentation, issue this command:

$ cmake --build build --target docs