Nice¶

This preset offers nice configuration defaults.

Classes¶

PythonSection¶

PythonSection(
    name: str | None = None, 
    params_python: dict | None = None, 
    wsgi_module: str | None = None, 
    wsgi_callable: str | Callable | None = None, 
    embedded_plugins: bool | None = True, 
    require_app: bool = True, 
    threads: bool | int = True, 
    **kwargs
)

Section

Basic nice configuration using Python plugin.

alarms ¶

.alarms: Alarms = Options(Alarms)

Alarms options group.

applications ¶

.applications: Applications = Options(Applications)

Applications options group.

caching ¶

.caching: Caching = Options(Caching)

Caching options group.

cheapening ¶

.cheapening: Cheapening = Options(Cheapening)

Cheapening options group.

empire ¶

.empire: Empire = Options(Empire)

Emperor and vassals options group.

locks ¶

.locks: Locks = Options(Locks)

Locks options group.

logging ¶

.logging: Logging = Options(Logging)

Logging options group.

main_process ¶

.main_process: MainProcess = Options(MainProcess)

Main process options group.

master_process ¶

.master_process: MasterProcess = Options(MasterProcess)

Master process options group.

monitoring ¶

.monitoring: Monitoring = Options(Monitoring)

Monitoring options group.

networking ¶

.networking: Networking = Options(Networking)

Networking options group.

plugin ¶

.plugin: bool | str = False

Indication this option group belongs to a plugin.

project_name ¶

.project_name()

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

python ¶

.python: Python = Options(Python)

Python options group.

queue ¶

.queue: Queue = Options(Queue)

Queue options group.

routing ¶

.routing: Routing = Options(Routing)

Routing related options group.

spooler ¶

.spooler: Spooler = Options(Spooler)

Spooler options group.

statics ¶

.statics: Statics = Options(Statics)

Static file serving options group.

subscriptions ¶

.subscriptions: Subscriptions = Options(Subscriptions)

Subscription services options group.

workers ¶

.workers: Workers = Options(Workers)

Workers options group.

as_configuration ¶

.as_configuration(
    **kwargs,  # (1)!
) -> Configuration

Configuration objects initializer arguments.

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

bootstrap ¶

.bootstrap(
    dsn: Strlist,  # (1)!
    allow_shared_sockets: bool | None = None,  # (2)!
    **init_kwargs: Any,  # (3)!
) -> TypeSection

Data source name, e.g:
- http://127.0.0.1:8000
- https://127.0.0.1:443?cert=/here/there.crt&key=/that/my.key
Note

Some schemas: fastcgi, http, https, raw, scgi, shared, udp, uwsgi, suwsgi, zeromq
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.
Additional initialization keyword arguments accepted by section type.

Constructs a section object performing its basic (default) configuration.

configure_certbot_https ¶

.configure_certbot_https(
    domain: str,  # (1)!
    webroot: str,  # (2)!
    address: str | None = None,  # (3)!
    allow_shared_sockets: bool | None = None,  # (4)!
    http_redirect: bool = False,  # (5)!
)

Domain name certificates issued for (the same as in -d option in the above command).
Directory to store challenge files to get and renew the certificate (the same as in -w option in the above command).
Address to bind socket to.
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.
Redirect HTTP requests to HTTPS if certificates exist.

Enables HTTPS using certificates from Certbot https://certbot.eff.org.

Note

This relies on webroot mechanism of Certbot - https://certbot.eff.org/docs/using.html#webroot

Sample command to get a certificate: ``certbot certonly --webroot -w /webroot/path/ -d mydomain.org``

configure_https_redirect ¶

.configure_https_redirect()

Enables HTTP to HTTPS redirect.

configure_logging_json ¶

.configure_logging_json(
    tpl_msg: str = '',  # (1)!
    tpl_ctx: dict | None = None,  # (2)!
)

Custom template string for the message.
Custom addition context template dictionary. The following macros are available for values: * src - uwsgi.req or uwsgi.out * msg - data from tpl_msg (if uwsgi.req) or out (if uwsgi.out) * dt_iso - iso datetime, e.g. 2025-06-06T22:47:03+0700 * ts_ms - timestamp, e.g. 1749224823443

Configures uWSGI output to be json-formatted.

configure_maintenance_mode ¶

.configure_maintenance_mode(
    trigger: Strpath,  # (1)!
    response: str,  # (2)!
)

This triggers maintenance mode responses. Should be a path to a file: if file exists, maintenance mode is on.

Response to give in maintenance mode.

Supported:
    1. File path - this file will be served in response.

    2. URLs starting with ``http`` - requests will be redirected there using 302.
      This is often discouraged, because it may have search ranking implications.

    3. Prefix ``app`` will replace your entire app with a maintenance one.
      Using this also prevents background tasks registration and execution
      (including scheduler, timers, signals).

      * If the value is `app` - the default maintenance application bundled with
        uwsgiconf would be used.

      * Format ``app::<your-module>:<your-app-function>`` instructs uwsgiconf to
        load your function as a maintenance app. E.g.: app::my_pack.my_module:my_func

Allows maintenance mode when a certain response is given for every request if a trigger is set.

configure_owner ¶

.configure_owner(
    owner: str = 'www-data',  # (1)!
    drop_after: str = '',  # (2)!
)

Sets user and group. Default: www-data.
When to drop privileges (e.g. if initially run as root):
- 'init' - drop after plugin initialization
- 'apps' - drop after apps loading

Shortcut to set process owner data.

derive_from ¶

.derive_from(
    section: TypeSection,  # (1)!
    name: str | None = None,  # (2)!
) -> TypeSection

Section to derive from,
New section name.

Creates a new section based on the given.

env ¶

.env(
    key: str, 
    value: Any = None, 
    unset: bool = False,  # (1)!
    asap: bool = False,  # (2)!
    update_local: bool = False,  # (3)!
) -> TypeSection

Whether to unset this variable.
If True env variable will be set as soon as possible.
Whether we need to set this value for local environment too. This could be useful in embedded mode.

Processes (sets/unsets) environment variable.

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

get_bundled_static_path ¶

.get_bundled_static_path(
    filename: str,  # (1)!
) -> str

File name to return path to.

Examples:
    * 403.html
    * 404.html
    * 500.html
    * 503.html

Returns a full path to a static HTML page file bundled with uwsgiconf.

get_log_format_default ¶

.get_log_format_default() -> str

Returns default log message format.

Note

Some params may be missing.

get_runtime_dir ¶

.get_runtime_dir(
    default: bool = True,  # (1)!
) -> Path

Whether to return [system] default if not set.

Directory to store runtime files. See .replace_placeholders()

Note

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

include ¶

.include(
    target: Union[Section,  list[Section],  str,  list[str]],  # (1)!
) -> TypeSection

File path or Section to include.

Includes target contents into config.

print_out ¶

.print_out(
    value: Any, 
    indent: str | None = None, 
    format_options: dict | str | None = None,  # (1)!
    asap: bool = False,  # (2)!
) -> TypeSection

text color
Print as soon as possible.

Prints out the given value.

print_plugins ¶

.print_plugins() -> TypeSection

Print out enabled plugins.

print_stamp ¶

.print_stamp() -> TypeSection

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

print_variables ¶

.print_variables() -> TypeSection

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

http://uwsgi-docs.readthedocs.io/en/latest/Configuration.html#magic-variables

replace_placeholders ¶

.replace_placeholders(value: Strlist | Pathlist | None) -> Strlist | None

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

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

set_fallback ¶

.set_fallback(
    target: Union[str,  Section],  # (1)!
) -> TypeSection

File path or Section to include.

Sets a fallback configuration for section.

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

set_placeholder ¶

.set_placeholder(key: str, value: str) -> TypeSection

Placeholders are custom magic variables defined during configuration time.

Note

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

set_plugins_params ¶

.set_plugins_params(
    plugins: list[str] | list[OptionsGroup] | str | OptionsGroup = None,  # (1)!
    search_dirs: Strlist = None,  # (2)!
    autoload: bool | None = None,  # (3)!
    required: bool = False,  # (4)!
) -> TypeSection

uWSGI plugins to load
Directories to search for uWSGI plugins.
Try to automatically load plugins when unknown options are found.
Load uWSGI plugins and exit on error.

Sets plugin-related parameters.

set_runtime_dir ¶

.set_runtime_dir(value: Strpath) -> TypeSection

Sets user-defined runtime directory value.

embedded_plugins_presets ¶

.embedded_plugins_presets()

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

BASIC¶

.BASIC: ClassVar[list[str]] = [plugin.strip() for plugin in (
    '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').split(',')]

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

PROBE ¶

.PROBE()

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

vars ¶

.vars()

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

http://uwsgi-docs.readthedocs.io/en/latest/Configuration.html#magic-variables

CONF_CURRENT_SECTION¶

.CONF_CURRENT_SECTION = '%x'

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

CONF_NAME_ORIGINAL¶

.CONF_NAME_ORIGINAL = '%o'

The original conf filename, as specified on the command line

CPU_CORES¶

.CPU_CORES = '%k'

Detected CPU count.

DIR_VASSALS¶

.DIR_VASSALS = '%v'

Vassals directory - pwd.

FORMAT_ESCAPE¶

.FORMAT_ESCAPE = '%['

ANSI escape \033. useful for printing colors

GROUP_ID¶

.GROUP_ID = '%g'

Use group ID.

GROUP_NAME¶

.GROUP_NAME = '%G'

Use group name.

HOST_NAME¶

.HOST_NAME = '%h'

Host name.

TIMESTAMP_STARTUP_MS¶

.TIMESTAMP_STARTUP_MS = '%T'

Unix time ms, gathered at instance startup

TIMESTAMP_STARTUP_S¶

.TIMESTAMP_STARTUP_S = '%t'

Unix time s, gathered at instance startup.

USER_ID¶

.USER_ID = '%u'

User ID.

USER_NAME¶

.USER_NAME = '%U'

User name.

VERSION¶

.VERSION = '%V'

uWSGI version number

get_descriptions ¶

.get_descriptions() -> dict[str, str]

Returns variable to description mapping.

Section¶

Section(
    name: str | None = None, 
    touch_reload: Strlist = None, 
    workers: int | None = None, 
    threads: int | bool | None = None, 
    mules: int | None = None, 
    owner: str | None = None, 
    log_into: str | None = None, 
    log_dedicated: bool | None = None, 
    process_prefix: str | None = None, 
    ignore_write_errors: bool | None = None, 
    **kwargs
)

_Section

Basic nice configuration.

alarms ¶

.alarms: Alarms = Options(Alarms)

Alarms options group.

applications ¶

.applications: Applications = Options(Applications)

Applications options group.

caching ¶

.caching: Caching = Options(Caching)

Caching options group.

cheapening ¶

.cheapening: Cheapening = Options(Cheapening)

Cheapening options group.

empire ¶

.empire: Empire = Options(Empire)

Emperor and vassals options group.

locks ¶

.locks: Locks = Options(Locks)

Locks options group.

logging ¶

.logging: Logging = Options(Logging)

Logging options group.

main_process ¶

.main_process: MainProcess = Options(MainProcess)

Main process options group.

master_process ¶

.master_process: MasterProcess = Options(MasterProcess)

Master process options group.

monitoring ¶

.monitoring: Monitoring = Options(Monitoring)

Monitoring options group.

networking ¶

.networking: Networking = Options(Networking)

Networking options group.

plugin ¶

.plugin: bool | str = False

Indication this option group belongs to a plugin.

project_name ¶

.project_name()

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

python ¶

.python: Python = Options(Python)

Python options group.

queue ¶

.queue: Queue = Options(Queue)

Queue options group.

routing ¶

.routing: Routing = Options(Routing)

Routing related options group.

spooler ¶

.spooler: Spooler = Options(Spooler)

Spooler options group.

statics ¶

.statics: Statics = Options(Statics)

Static file serving options group.

subscriptions ¶

.subscriptions: Subscriptions = Options(Subscriptions)

Subscription services options group.

workers ¶

.workers: Workers = Options(Workers)

Workers options group.

as_configuration ¶

.as_configuration(
    **kwargs,  # (1)!
) -> Configuration

Configuration objects initializer arguments.

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

bootstrap ¶

.bootstrap(
    dsn: Strlist,  # (1)!
    allow_shared_sockets: bool | None = None,  # (2)!
    **init_kwargs: Any,  # (3)!
) -> TypeSection

Data source name, e.g:
- http://127.0.0.1:8000
- https://127.0.0.1:443?cert=/here/there.crt&key=/that/my.key
Note

Some schemas: fastcgi, http, https, raw, scgi, shared, udp, uwsgi, suwsgi, zeromq
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.
Additional initialization keyword arguments accepted by section type.

Constructs a section object performing its basic (default) configuration.

configure_certbot_https¶

.configure_certbot_https(
    domain: str,  # (1)!
    webroot: str,  # (2)!
    address: str | None = None,  # (3)!
    allow_shared_sockets: bool | None = None,  # (4)!
    http_redirect: bool = False,  # (5)!
)

Domain name certificates issued for (the same as in -d option in the above command).
Directory to store challenge files to get and renew the certificate (the same as in -w option in the above command).
Address to bind socket to.
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.
Redirect HTTP requests to HTTPS if certificates exist.

Enables HTTPS using certificates from Certbot https://certbot.eff.org.

Note

This relies on webroot mechanism of Certbot - https://certbot.eff.org/docs/using.html#webroot

Sample command to get a certificate: ``certbot certonly --webroot -w /webroot/path/ -d mydomain.org``

configure_https_redirect¶

.configure_https_redirect()

Enables HTTP to HTTPS redirect.

configure_logging_json¶

.configure_logging_json(
    tpl_msg: str = '',  # (1)!
    tpl_ctx: dict | None = None,  # (2)!
)

Custom template string for the message.
Custom addition context template dictionary. The following macros are available for values: * src - uwsgi.req or uwsgi.out * msg - data from tpl_msg (if uwsgi.req) or out (if uwsgi.out) * dt_iso - iso datetime, e.g. 2025-06-06T22:47:03+0700 * ts_ms - timestamp, e.g. 1749224823443

Configures uWSGI output to be json-formatted.

configure_maintenance_mode¶

.configure_maintenance_mode(
    trigger: Strpath,  # (1)!
    response: str,  # (2)!
)

This triggers maintenance mode responses. Should be a path to a file: if file exists, maintenance mode is on.

Response to give in maintenance mode.

Supported:
    1. File path - this file will be served in response.

    2. URLs starting with ``http`` - requests will be redirected there using 302.
      This is often discouraged, because it may have search ranking implications.

    3. Prefix ``app`` will replace your entire app with a maintenance one.
      Using this also prevents background tasks registration and execution
      (including scheduler, timers, signals).

      * If the value is `app` - the default maintenance application bundled with
        uwsgiconf would be used.

      * Format ``app::<your-module>:<your-app-function>`` instructs uwsgiconf to
        load your function as a maintenance app. E.g.: app::my_pack.my_module:my_func

Allows maintenance mode when a certain response is given for every request if a trigger is set.

configure_owner¶

.configure_owner(
    owner: str = 'www-data',  # (1)!
    drop_after: str = '',  # (2)!
)

Sets user and group. Default: www-data.
When to drop privileges (e.g. if initially run as root):
- 'init' - drop after plugin initialization
- 'apps' - drop after apps loading

Shortcut to set process owner data.

derive_from ¶

.derive_from(
    section: TypeSection,  # (1)!
    name: str | None = None,  # (2)!
) -> TypeSection

Section to derive from,
New section name.

Creates a new section based on the given.

env ¶

.env(
    key: str, 
    value: Any = None, 
    unset: bool = False,  # (1)!
    asap: bool = False,  # (2)!
    update_local: bool = False,  # (3)!
) -> TypeSection

Whether to unset this variable.
If True env variable will be set as soon as possible.
Whether we need to set this value for local environment too. This could be useful in embedded mode.

Processes (sets/unsets) environment variable.

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

get_bundled_static_path ¶

.get_bundled_static_path(
    filename: str,  # (1)!
) -> str

File name to return path to.

Examples:
    * 403.html
    * 404.html
    * 500.html
    * 503.html

Returns a full path to a static HTML page file bundled with uwsgiconf.

get_log_format_default¶

.get_log_format_default() -> str

Returns default log message format.

Note

Some params may be missing.

get_runtime_dir ¶

.get_runtime_dir(
    default: bool = True,  # (1)!
) -> Path

Whether to return [system] default if not set.

Directory to store runtime files. See .replace_placeholders()

Note

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

include ¶

.include(
    target: Union[Section,  list[Section],  str,  list[str]],  # (1)!
) -> TypeSection

File path or Section to include.

Includes target contents into config.

print_out ¶

.print_out(
    value: Any, 
    indent: str | None = None, 
    format_options: dict | str | None = None,  # (1)!
    asap: bool = False,  # (2)!
) -> TypeSection

text color
Print as soon as possible.

Prints out the given value.

print_plugins ¶

.print_plugins() -> TypeSection

Print out enabled plugins.

print_stamp ¶

.print_stamp() -> TypeSection

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

print_variables ¶

.print_variables() -> TypeSection

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

http://uwsgi-docs.readthedocs.io/en/latest/Configuration.html#magic-variables

replace_placeholders ¶

.replace_placeholders(value: Strlist | Pathlist | None) -> Strlist | None

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

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

set_fallback ¶

.set_fallback(
    target: Union[str,  Section],  # (1)!
) -> TypeSection

File path or Section to include.

Sets a fallback configuration for section.

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

set_placeholder ¶

.set_placeholder(key: str, value: str) -> TypeSection

Placeholders are custom magic variables defined during configuration time.

Note

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

set_plugins_params ¶

.set_plugins_params(
    plugins: list[str] | list[OptionsGroup] | str | OptionsGroup = None,  # (1)!
    search_dirs: Strlist = None,  # (2)!
    autoload: bool | None = None,  # (3)!
    required: bool = False,  # (4)!
) -> TypeSection

uWSGI plugins to load
Directories to search for uWSGI plugins.
Try to automatically load plugins when unknown options are found.
Load uWSGI plugins and exit on error.

Sets plugin-related parameters.

set_runtime_dir ¶

.set_runtime_dir(value: Strpath) -> TypeSection

Sets user-defined runtime directory value.

embedded_plugins_presets ¶

.embedded_plugins_presets()

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

BASIC¶

.BASIC: ClassVar[list[str]] = [plugin.strip() for plugin in (
    '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').split(',')]

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

PROBE ¶

.PROBE()

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

vars ¶

.vars()

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

http://uwsgi-docs.readthedocs.io/en/latest/Configuration.html#magic-variables

CONF_CURRENT_SECTION¶

.CONF_CURRENT_SECTION = '%x'

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

CONF_NAME_ORIGINAL¶

.CONF_NAME_ORIGINAL = '%o'

The original conf filename, as specified on the command line

CPU_CORES¶

.CPU_CORES = '%k'

Detected CPU count.

DIR_VASSALS¶

.DIR_VASSALS = '%v'

Vassals directory - pwd.

FORMAT_ESCAPE¶

.FORMAT_ESCAPE = '%['

ANSI escape \033. useful for printing colors

GROUP_ID¶

.GROUP_ID = '%g'

Use group ID.

GROUP_NAME¶

.GROUP_NAME = '%G'

Use group name.

HOST_NAME¶

.HOST_NAME = '%h'

Host name.

TIMESTAMP_STARTUP_MS¶

.TIMESTAMP_STARTUP_MS = '%T'

Unix time ms, gathered at instance startup

TIMESTAMP_STARTUP_S¶

.TIMESTAMP_STARTUP_S = '%t'

Unix time s, gathered at instance startup.

USER_ID¶

.USER_ID = '%u'

User ID.

USER_NAME¶

.USER_NAME = '%U'

User name.

VERSION¶

.VERSION = '%V'

uWSGI version number

get_descriptions ¶

.get_descriptions() -> dict[str, str]

Returns variable to description mapping.