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
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.
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, defaults to cwd.
backlog	`--backlog`	The maximum number of pending connections.
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.
debug	`--debug`	Enable debug mode, i.e. extra logging and checks.
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 complete.
group	`-g`, `--group`	Group to own any unix sockets.
h11_max_incomplete_size	N/A	The max HTTP/2 request line + headers size in bytes.
h2_max_concurrent_streams	N/A	Maximum number of HTTP/2 concurrent streams.
h2_max_header_list_size	N/A	Maximum number of HTTP/2 headers.
h2_max_inbound_frame_size	N/A	Maximum size of a HTTP/2 frame.
include_server_header	N/A	Include the `Server: Hypercorn` header, default 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.
keyfile	`--keyfile`	Path to the SSL key file.
logconfig	`--log-config`	A Python logging configuration file.
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.
max_app_queue_size	N/A	The maximum number of events to queue up sending to the ASGI application.
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.
ssl_handshake_timeout	N/A	Timeout when waiting for SSL handshakes to complete.
startup_timeout	N/A	Timeout when waiting for Lifespan startups to complete.
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.
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.

Binds

Dispatch to multiple ASGI applications