Using the Modpack Installer Utility

The modpack installer is a simple tool to download custom Freeciv21 content called modpacks from the Internet, and automatically install them into the correct location to be used by the Freeciv21 client and server.

A modpack can consist of one or more of:

  • rulesets for game rules

  • scenarios for game maps (with or without players/cities/etc)

  • tilesets for game graphics

  • soundsets or musicsets for sound effects and in-game music

They can be installed using the modpack installer tool freeciv21-modpack-qt that comes with the standard installation. There is also a command-line-only tool called freeciv21-modpack, which is mainly useful for headless game servers.

In standard Freeciv21 builds, when you start the graphical modpack installer, it will show a list of modpacks curated by the Freeciv21 developers and community. You can select one and click Install modpack; the tool will download the files for the selected modpack, and any other modpacks it depends on, and install them ready for the main Freeciv21 programs to use.

Freeciv21 Modpack Installer Qt GUI application

You can also point the installer at modpacks or lists on other servers:

  • If someone has given you an individual modpack URL (ending in .json), you can paste it into the Modpack URL box, and when you click Install modpack, the modpack will immediately downloaded and install.


If you have been given a URL ending up .modpack or .mpdl, that is probably for legacy Freeciv and not Freeciv21. These modpack files are not compatible with Freeciv21.

  • If someone has given you a URL for a list of modpacks (also ending in .json) and you want to browse them with the standard Freeciv21 modpack installer build, you need to start the tool with that URL on its command line, for instance:

freeciv21-modpack --List


The capital letter in --List

The tool has some other command-line options, but most users will not need to use them. Use --help for a list of them.

Once you have installed a modpack, how you use it depends on the modpack type:

  • Scenarios (maps) should be listed under Start scenario game from the client start page, or from the game server prompt via /list scenarios.


For network play, scenarios need only be installed on the game server.

  • Rulesets should appear on the Ruleset drop-down from the client’s Start new game page. On the game server, you can load a ruleset with /read <name> or failing that perhaps /rulesetdir <name>.

  • Tilesets should appear for selection in the local client options, in the appropriate topology-specific Tileset drop-down under Graphics.


Tilesets should be installed on the client machine.

  • Soundsets and musicsets should appear in the dropdowns on the Sound page of the local client options.

With standard Freeciv21 builds, modpacks get installed into a per-user area, not into the main Freeciv21 installation. So you shouldn’t need any special permissions to download them, and if you uninstall the Freeciv21 game, any modpacks you downloaded are likely to remain on your system. Conversely, if you delete downloaded modpacks by hand, the standard rulesets, tilesets, etc. supplied with Freeciv21 won’t be touched.

The precise location where files are downloaded to depends on your build and platform. For Unix systems, it is likely to be under the hidden ~/.local/share/freeciv21 directory in your home directory. For Windows based sytems it will be in your user profile directory in a hidden AppData folder, typically, C:\Users\[MyUserName]\AppData\Roaming\Freeciv21 It is likely to be near where the Freeciv21 client stores its saved games.

Most modpacks are specific to a particular major version of Freeciv21; for instance, while a 3.0 ruleset or tileset can be used with all Freeciv21 3.0.x releases, it cannot be used as-is with any 3.1.x release. So, most modpacks are installed in a specific directory for the major version, such as ~/.local/share/freeciv21/3.1/ on Unix.


The modpack installer displays which version it will install for at the top of its window.

An exception to this is scenario maps; scenarios created for one version of Freeciv21 can usually be loaded in later versions, so they are installed in a version-independent location (typically ~/.local/share/freeciv21/scenarios/ on Unix).

Once a modpack is installed, there is no uninstall action, and if you remove the files by hand, the installer will still consider the modpack to be installed; the installer maintains its own database (.control/modpacks.db) listing which modpack versions are installed, but does not keep track of which files were installed by which modpack. If the database gets out of sync with reality (or is deleted), it’s harmless for already installed modpacks and the main Freeciv21 programs (which do not consult the database), but can confuse the modpack installer’s dependency tracking later.

Modpacks consist mostly of data files read by the Freeciv21 engine; they do not contain compiled binary code (and are thus platform-independent). Rulesets can contain code in the form of Lua scripts, but this is executed in a sandbox to prevent obvious security exploits. Modpacks are installed to a specific area and cannot overwrite arbitrary files on your system. Nevertheless, you should only install modpacks from sources you trust.