class uwsgiconf.options.empire.Empire(*args, **kwargs)

Emperor and his vassals.

If you need to deploy a big number of apps on a single server, or a group of servers, the Emperor mode is just the ticket.

set_emperor_params(*, vassals_home=None, name=None, scan_interval=None, pid_file=None, spawn_asap=None, stats_address=None, trigger_socket=None, links_no_follow=None)


The emperor should generally not be run with master, unless master features like advanced logging are specifically needed.


The emperor should generally be started at server boot time and left alone, not reloaded/restarted except for uWSGI upgrades; emperor reloads are a bit drastic, reloading all vassals at once. Instead vassals should be reloaded individually when needed, in the manner of the imperial monitor in use.

  • vassals_home (str|list[str]) – Set vassals home and enable Emperor mode.
  • name (str) – Set the Emperor process name.
  • scan_interval (int) – Set the Emperor scan frequency. Default: 3 seconds.
  • pid_file (str) – Write the Emperor pid in the specified file.
  • spawn_asap (bool) – Spawn the Emperor as soon as possible.
  • stats_address (str) – Run the Emperor stats server on specified address.
  • trigger_socket (str) – Enable the Emperor trigger socket.
  • links_no_follow (bool) – Do not follow symlinks when checking for mtime.

Print out enabled imperial monitors.

set_emperor_command_params(command_socket=None, *, wait_for_command=None, wait_for_command_exclude=None)

Emperor commands related parameters.

  • command_socket (str) – Enable the Emperor command socket. It is a channel allowing external process to govern vassals.
  • wait_for_command (bool) – Always wait for a ‘spawn’ Emperor command before starting a vassal.
  • wait_for_command_exclude (str|list[str]) – Vassals that will ignore wait_for_command.
set_vassals_wrapper_params(*, wrapper=None, overrides=None, fallbacks=None)

Binary wrapper for vassals parameters.

  • wrapper (str) – Set a binary wrapper for vassals.
  • overrides (str|list[str]) – Set a binary wrapper for vassals to try before the default one
  • fallbacks (str|list[str]) – Set a binary wrapper for vassals to try as a last resort. Allows you to specify an alternative binary to execute when running a vassal and the default binary_path is not found (or returns an error).
set_throttle_params(*, level=None, level_max=None)

Throttling options.

  • level (int) – Set throttling level (in milliseconds) for bad behaving vassals. Default: 1000.
  • level_max (int) – Set maximum throttling level (in milliseconds) for bad behaving vassals. Default: 3 minutes.
set_tolerance_params(*, for_heartbeat=None, for_cursed_vassals=None)

Various tolerance options.

set_mode_tyrant_params(enable=None, *, links_no_follow=None, use_initgroups=None)

Tyrant mode (secure multi-user hosting).

In Tyrant mode the Emperor will run the vassal using the UID/GID of the vassal configuration file.

  • enable – Puts the Emperor in Tyrant mode.
  • links_no_follow (bool) – Do not follow symlinks when checking for uid/gid in Tyrant mode.
  • use_initgroups (bool) – Add additional groups set via initgroups() in Tyrant mode.
set_mode_broodlord_params(zerg_count=None, *, vassal_overload_sos_interval=None, vassal_queue_items_sos=None)

This mode is a way for a vassal to ask for reinforcements to the Emperor.

Reinforcements are new vassals spawned on demand generally bound on the same socket.


If you are looking for a way to dynamically adapt the number of workers of an instance, check the Cheaper subsystem - adaptive process spawning mode.

Broodlord mode is for spawning totally new instances.

  • zerg_count (int) – Maximum number of zergs to spawn.
  • vassal_overload_sos_interval (int) – Ask emperor for reinforcement when overloaded. Accepts the number of seconds to wait between asking for a new reinforcements.
  • vassal_queue_items_sos (int) – Ask emperor for sos if listen queue (backlog) has more items than the value specified