Configuration and Section

Configuration and Section are two types you’ll have to mainly deal with.

class uwsgiconf.config.Section(name: str = None, *, runtime_dir: str = None, project_name: str = None, strict_config: bool = None, style_prints: bool = False, embedded_plugins: Union[Callable, List[str]] = None, **kwargs)

Configuration section.

Options within configuration section are gathered into groups:

  • alarms
  • caching
  • master_process
  • workers
  • etc.

Next to all public methods of groups are for setting configuration parameters. Such methods return section object to allow chaining.

You can pass options group basic parameters into (the following are all the same):

  • set_basic_params() as in section.workers.set_basic_params(count=3)

  • __call__ as in section.workers(count=3)

  • section initializer using params_ prefixed group name:

  • name – Configuration section name.
  • runtime_dir

    Directory to store runtime files. See .replace_placeholders()


    This can be used to store PID files, sockets, master FIFO, etc.

  • project_name – Project name (alias) to be used to differentiate projects. See .replace_placeholders().
  • strict_config

    Enable strict configuration parsing. If any unknown option is encountered in a configuration file, an error is shown and uWSGI quits.

    To use placeholder variables when using strict mode, use the set-placeholder option.

  • style_prints – Enables styling (e.g. colouring) for print_ family methods. Could be nice for console and distracting in logs.
  • embedded_plugins

    List of embedded plugins. Plugins from that list will be considered already loaded so uwsgiconf won’t instruct uWSGI to load it if required.

    See .embedded_plugins_presets for shortcuts.


    • If you installed uWSGI using PyPI package there should already be basic plugins embedded.
    • If using Ubuntu distribution you have to install plugins as separate packages.

alias of uwsgiconf.options.alarms.Alarms


alias of uwsgiconf.options.applications.Applications


alias of uwsgiconf.options.caching.Caching


alias of uwsgiconf.options.workers_cheapening.Cheapening


alias of uwsgiconf.options.empire.Empire


alias of uwsgiconf.options.locks.Locks


alias of uwsgiconf.options.logging.Logging


alias of uwsgiconf.options.main_process.MainProcess


alias of uwsgiconf.options.master_process.MasterProcess


alias of uwsgiconf.options.monitoring.Monitoring


alias of uwsgiconf.options.networking.Networking


alias of uwsgiconf.options.queue.Queue


alias of uwsgiconf.options.routing.Routing


alias of uwsgiconf.options.spooler.Spooler


alias of uwsgiconf.options.statics.Statics


alias of uwsgiconf.options.subscriptions.Subscriptions


alias of uwsgiconf.options.workers.Workers


alias of uwsgiconf.options.python.Python

class embedded_plugins_presets

These are plugin presets that can be used as embedded_plugins values.

BASIC = ['ping', 'cache', 'nagios', 'rrdtool', 'carbon', 'rpc', 'corerouter', 'fastrouter', 'http', 'ugreen', 'signal', 'syslog', 'rsyslog', 'logsocket', 'router_uwsgi', 'router_redirect', 'router_basicauth', 'zergpool', 'redislog', 'mongodblog', 'router_rewrite', 'router_http', 'logfile', 'router_cache', 'rawrouter', 'router_static', 'sslrouter', 'spooler', 'cheaper_busyness', 'symcall', 'transformation_tofile', 'transformation_gzip', 'transformation_chunked', 'transformation_offload', 'router_memcached', 'router_redis', 'router_hash', 'router_expires', 'router_metrics', 'transformation_template', 'stats_pusher_socket', 'router_fcgi']

Basic set of embedded plugins. This set is used in uWSGI package from PyPI.

static PROBE(uwsgi_binary: str = None)

This preset allows probing real uWSGI to get actual embedded plugin list.

replace_placeholders(value: Union[str, List[str], None]) → Union[str, List[str], None]

Replaces placeholders that can be used e.g. in filepaths.

Supported placeholders:
  • {project_runtime_dir}
  • {project_name}
  • {runtime_dir}

Project name (alias) to be used to differentiate projects. See .replace_placeholders().

get_runtime_dir(*, default: bool = True) → str

Directory to store runtime files. See .replace_placeholders()


This can be used to store PID files, sockets, master FIFO, etc.

Parameters:default – Whether to return [system] default if not set.
set_runtime_dir(value) → TypeSection

Sets user-defined runtime directory value.

Parameters:value (str) –
as_configuration(**kwargs) → uwsgiconf.config.Configuration

Returns configuration object including only one (this very) section.

Parameters:kwargs – Configuration objects initializer arguments.
print_plugins() → TypeSection

Print out enabled plugins.

print_stamp() → TypeSection

Prints out a stamp containing useful information, such as what and when has generated this configuration.

print_out(value: Any, *, indent: str = None, format_options: Union[dict, str] = None, asap: bool = False) → TypeSection

Prints out the given value.

  • value
  • indent
  • format_options – text color
  • asap – Print as soon as possible.
print_variables() → TypeSection

Prints out magic variables available in config files alongside with their values and descriptions. May be useful for debugging.

set_plugins_params(*, plugins: Union[List[str], List[uwsgiconf.base.OptionsGroup], str, uwsgiconf.base.OptionsGroup] = None, search_dirs: Union[str, List[str]] = None, autoload: bool = None, required: bool = False) → TypeSection

Sets plugin-related parameters.

  • plugins – uWSGI plugins to load
  • search_dirs – Directories to search for uWSGI plugins.
  • autoload – Try to automatically load plugins when unknown options are found.
  • required – Load uWSGI plugins and exit on error.
set_fallback(target: Union[str, Section]) → TypeSection

Sets a fallback configuration for section.

Re-exec uWSGI with the specified config when exit code is 1.

Parameters:target – File path or Section to include.
set_placeholder(key: str, value: str) → TypeSection

Placeholders are custom magic variables defined during configuration time.


These are accessible, like any uWSGI option, in your application code via .runtime.platform.uwsgi.config.

  • key
  • value
env(key: str, value: Any = None, *, unset: bool = False, asap: bool = False, update_local: bool = False) → TypeSection

Processes (sets/unsets) environment variable.

If is not given in set mode value will be taken from current env.

  • key
  • value
  • unset – Whether to unset this variable.
  • asap – If True env variable will be set as soon as possible.
  • update_local – Whether we need to set this value for local environment too. This could be useful in embedded mode.
include(target: Union[Section, List[Section], str, List[str]]) → TypeSection

Includes target contents into config.

Parameters:target – File path or Section to include.
classmethod derive_from(section: TypeSection, *, name: str = None) → TypeSection

Creates a new section based on the given.

  • section – Section to derive from,
  • name – New section name.
class vars

The following variables also known as magic variables could be used as option values where appropriate.


uWSGI version number


ANSI escape 033. useful for printing colors


The current section identifier, eg. conf.ini:section.


The original conf filename, as specified on the command line


Unix time s, gathered at instance startup.


Unix time ms, gathered at instance startup


Vassals directory - pwd.

HOST_NAME = '%h'

Host name.

CPU_CORES = '%k'

Detected CPU count.

USER_ID = '%u'

User ID.


User name.

GROUP_ID = '%g'

Use group ID.


Use group name.

classmethod get_descriptions() → Dict[str, str]

Returns variable to description mapping.

classmethod bootstrap(dsn: Union[str, List[str]], *, allow_shared_sockets: bool = None, **init_kwargs) → TypeSection

Constructs a section object performing it’s basic (default) configuration.

  • dsn

    Data source name, e.g: * *


    Some schemas: fastcgi, http, https, raw, scgi, shared, udp, uwsgi, suwsgi, zeromq

  • allow_shared_sockets – Allows using shared sockets to bind to privileged ports. If not provided automatic mode is enabled: shared are allowed if current user is not root.
  • init_kwargs – Additional initialization keyword arguments accepted by section type.
class uwsgiconf.config.Configuration(sections: List[uwsgiconf.config.Section] = None, *, autoinclude_sections: bool = False, alias: str = None)

Configuration is comprised from one or more Sections and could be represented in format natively supported by uWSGI.

  • sections – If not provided, empty section will be automatically generated.
  • autoinclude_sections – Whether to include in the first sections all subsequent sections.
  • alias – Configuration alias. This will be used in tofile as file name.
format(*, do_print: bool = False, stamp: bool = True, formatter: str = 'ini') → Union[str, List[str]]

Applies formatting to configuration.

  • do_print – Whether to print out formatted config.
  • stamp – Whether to add stamp data to the first configuration section.
  • formatter – Formatter alias to format options. Default: ini.
print_ini() → Union[str, List[str]]

Print out this configuration as .ini.

tofile(filepath: Union[str, pathlib.Path] = None) → str

Saves configuration into a file and returns its path.

Convenience method.

Parameters:filepath – Filepath to save configuration into. If not provided a temporary file will be automatically generated.
uwsgiconf.config.configure_uwsgi(configurator_func: Callable) → Optional[List[uwsgiconf.config.Configuration]]

Allows configuring uWSGI using Configuration objects returned by the given configuration function.

Returns a list with detected configurations or None if called from within uWSGI (e.g. when trying to load WSGI application).

# In configuration module, e.g ``

from uwsgiconf.config import configure_uwsgi

Parameters:configurator_func – Function which return a list on configurations.