Configuring#

Hypercorn is configured via a command line arguments, or via a hypercorn.config.Config instance, which can be created manually, loaded from a TOML, Python file, Python module, or a dictionary instance.

Via a TOML file#

TOML is the prefered format for Hypercorn configuration files. Files in this format can be loaded via the command line using the -c, --config option e.g.

hypercorn --config file_path/file_name.toml

To load programatically hypercorn.config.Config.from_toml() can be used,

config = Config()
config.from_toml("file_path/file_name.toml")

Via a Python module#

A Python module or an instance within a python module can be used to configure Hypercorn. In both cases the attributes matching configuration values will be used. This can be specified via the command line using the -c, --config option with the python: prefix e.g.

hypercorn --config python:module_name

To load programatically hypercorn.config.Config.from_object() can be used,

config = Config()
config.from_object("module_name.instance")

Via a Python file#

A Python file can be loaded and the attributes matching configuration values used to configure Hypercorn. This can be specified via the command line using the -c, --config option with the file: prefix e.g.

hypercorn --config file:file_path/file_name.py

To load programatically hypercorn.config.Config.from_pyfile() can be used,

config = Config()
config.from_pyfile("file_path/file_name.py")

Configuration options#

Attribute

Command line

Purpose

Default

access_log_format

--access-logformat

The log format for the access log, see Logging.

accesslog

--access-logfile

The target logger for access logs, use - for stdout.

alpn_protocols

N/A

The HTTP protocols to advertise over ALPN.

h2 and http/1.1

alt_svc_headers

N/A

List of header values to return as Alt-Svc headers.

application_path

N/A

The path location of the ASGI application.

cwd

backlog

--backlog

The maximum number of pending connections.

100

bind

-b, --bind

The TCP host/address to bind to. Should be either host:port, host, unix:path or fd://num, e.g. 127.0.0.1:5000, 127.0.0.1, unix:/tmp/socket or fd://33 respectively.

ca_certs

--ca-certs

Path to the SSL CA certificate file.

certfile

--certfile

Path to the SSL certificate file.

ciphers

--ciphers

Ciphers to use for the SSL setup.

ECDHE+AESGCM

debug

--debug

Enable debug mode, i.e. extra logging and checks.

False

dogstatsd_tags

N/A

DogStatsd format tag, see Statsd Logging.

errorlog

--error-logfile --log-file

The target location for the error log, use - for stderr.

graceful_timeout

--graceful-timeout

Time to wait after SIGTERM or Ctrl-C for any remaining requests (tasks) to

read_timeout

--read-timeout

Seconds to wait before timing out reads on TCP sockets.

No timeout.

group

-g, --group

Group to own any unix sockets.

h11_max_incomplete_size

N/A

The max HTTP/1.1 request line + headers size in bytes.

16KiB

h2_max_concurrent_streams

N/A

Maximum number of HTTP/2 concurrent streams.

100

h2_max_header_list_size

N/A

Maximum number of HTTP/2 headers.

65536

h2_max_inbound_frame_size

N/A

Maximum size of a HTTP/2 frame.

16KiB

include_date_header

N/A

Include the Date: Tue, 15 Nov 1994 08:12:31 GMT header.

True

include_server_header

N/A

Include the Server: Hypercorn header.

True

insecure_bind

--insecure-bind

The TCP host/address to bind to. SSL options will not apply to these binds. See bind for formatting options. Care must be taken! See HTTP -> HTTPS redirection docs.

keep_alive_timeout

--keep-alive

Seconds to keep inactive connections alive before closing.

5s

keyfile

--keyfile

Path to the SSL key file.

logconfig

--log-config

A Python logging configuration file. This can be prefixed with ‘json:’ or ‘toml:’ to load the configuration from a file in that format.

The logging ini format.

logconfig_dict

N/A

A Python logging configuration dictionary.

logger_class

N/A

Type of class to use for logging.

loglevel

--log-level

The (error) log level.

INFO

max_app_queue_size

N/A

The maximum number of events to queue up sending to the ASGI application.

10

pid_path

-p, --pid

Location to write the PID (Program ID) to.

quic_bind

--quic-bind

The UDP/QUIC host/address to bind to. See bind for formatting options.

root_path

--root-path

The setting for the ASGI root_path variable.

server_names

--server-name

The hostnames that can be served, requests to different hosts will be responded to with 404s.

shutdown_timeout

N/A

Timeout when waiting for Lifespan shutdowns to complete.

60s

ssl_handshake_timeout

N/A

Timeout when waiting for SSL handshakes to complete.

60s

startup_timeout

N/A

Timeout when waiting for Lifespan startups to complete.

60s

statsd_host

--statsd-host

The host:port of the statsd server.

statsd_prefix

--statsd-prefix

Prefix for all statsd messages.

umask

-m, --umask

The permissions bit mask to use on any unix sockets.

use_reloader

--reload

Enable automatic reloads on code changes.

user

-u, --user

User to own any unix sockets.

verify_flags

N/A

SSL context verify flags.

verify_mode

--verify-mode

SSL verify mode for peer’s certificate, see ssl.VerifyMode enum for possible values.

websocket_max_message_size

N/A

Maximum size of a WebSocket frame.

16MiB

websocket_ping_interval

--websocket-ping-interval

If set this is the time in seconds between pings sent to the client. This can be used to keep the websocket connection alive.

worker_class

-k, --worker-class

The type of worker to use. Options include asyncio, uvloop (pip install hypercorn[uvloop]), and trio (pip install hypercorn[trio]).

workers

-w, --workers

The number of workers to spawn and use.

1

wsgi_max_body_size

N/A

The maximum size of a body that will be accepted in WSGI mode.

16MiB