Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

Configuring PyPlanet

Settings method is the method to read out settings. This can be one of the following methods/backends:

  • python: Default, the python loader uses the files and in the PYPLANET_SETTINGS_MODULE provided.
  • json: Read json files base.json and apps.json in the provided PYPLANET_SETTINGS_DIRECTORY directory.
  • yaml: Read yaml files base.yaml and apps.yaml in the provided PYPLANET_SETTINGS_DIRECTORY directory.

Settings module (python only) is where the PyPlanet settings are stored for python backend. You provide the settings module by providing the environment variable PYPLANET_SETTINGS_MODULE. Most of the times this is set in the

In most cases this settings module is settings and is located at the project root subfolder settings.

Settings directory (json and yaml only) is where the two configuration files are located for the file based backends such as JSON or YAML.

Split files is the default, based on the CLI project generation. This will create two files inside of the settings module, the one is for apps ( and the other for all base configuration ( For both other backends its quite the same.

Pools are the different instances that will be running from PyPlanet. PyPlanet supports multiple controllers from a single setup and project, and even a start command. We are just spawning subprocesses when you start PyPlanet. More information about this setup and architecture on the Architecture overview.

Case sensitive: Only the keys are not case insensitive (with exception of the Python backend). The value and the subkeys are all case sensitive!


In the examples in this document you often find an dictionary with the key being default. This is a Pool aware setting and is different for every pool.

If you are going to add another pool, you should add the pool name to the keys of the dictionary, and fill the value like it is in the examples given here.

Also, the JSON examples always contain the opening and closing brackets in the examples. In a real file you would have these only once around the whole file.

Debug Mode (base)

In most cases you don't have to use this setting. This setting is only here for developers. While you are in debug mode, there will be More verbose output, no reporting of exceptions, and debugging of SQL queries.

When generating a project with the CLI, you will find this setting to be looking at your environment variable PYPLANET_DEBUG. Therefor, enable debug by starting PyPlanet with PYPLANET_DEBUG=1. Or changing the setting to DEBUG = True. This only works for the python config backend


Please enable DEBUG when developing, as it won't send reports to the PyPlanet developers, which needs time to investigate and cleanup.

Pool defining (base)

You need to define the pools you want to start and have activated with the POOLS list.

Owners (base)

Because you want to have admin access at the first boot, you have to define a few master admin logins here. This is optional but will help you to get started directly after starting. This setting is pool aware.

Database configuration (

The database configuration is mostly the first setting you will adjust to your needs. Currently PyPlanet has support for these database drivers:

  • peewee_async.MySQLDatabase: Using PyMySQL, a full Python based driver. (Supports MariaDB and PerconaDB).
  • peewee_async.PostgresqlDatabase: Using a full native Python driver.

Creating database:

You will have to create the database scheme yourself. Make sure you create it with a database collate that is based on UTF-8. We require for MySQL: utf8mb4_unicode_ci to work with the new symbols in Maniaplanet. Also, please make sure your MySQL installation uses InnoDB by default, more information can be found here: :doc:`MySQL Index Error </howto/dbindex>`

Create MySQL Database by running this command:

  COLLATE utf8mb4_unicode_ci;


Configuration can follow the following examples:

Dedicated Server (base)

This one is pretty important, and pretty simple too. Look at the examples bellow, and you know how to set this up!

Server files settings (base)

Some of these settings are required to be able to save match settings and to save the blacklisted players for example.

Storage (base)

This may need some explanation, why is this here? We wanted to be able to run PyPlanet on a separate machine as the dedicated is. But also access files from the dedicated for investigating maps, loading and writing maps and settings.

To be able to make this simple, and robust, we will implement several so called storage drivers that will work local or remote (currently only local).

Local Dedicated

If you run your dedicated server locally, you should use the following setting:

Cache (base)


This functionality is not (yet) implemented. Please don't define CACHE setting.

Self Upgrade (base)

New since 0.6.0 is the self-upgrader where the master admins can self upgrade the PyPlanet installation from within the game. You don't want this to be enabled on shared servers (hosting environments) as it may break your installation.


Using the self-upgrade (//upgrade and `pyplanet upgrade`) is very experimental. The method can break your installation. We don't guarantee the working of the method.

We advice to use the manual PIP method of upgrading over the in-game upgrading process!

Songs (base)


This setting only works in combination with the music_server app. Enable the app by adding the app in your (or apps.json/apps.yaml).

You can add URL's of the music to the SONGS list.

Logging (base)

By default (from version 0.5.0) rotating logging is enabled by default but writing is disabled by default. The settings bellow can be adjusted to meet your requirements.

Enabling apps (apps)

You can enable apps in the APPS setting. This is pretty simple and straight forward. The order doesn't make a difference when starting/loading PyPlanet.


When new contributed apps will come available, you have to manually enable it in your settings. Please take a look at our :doc:`Change Log </changelog>` for details on changes.