# 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
h11_pass_raw_headers | N/A | Pass the raw headers from h11 to the Request object, which preserves header casing. | `False`
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_max_requests | N/A | Maximum number of requests before connection is closed. HTTP/1 & HTTP/2 only. | 1000
keep_alive_timeout | `--keep-alive` | Seconds to keep inactive connections alive before closing. | 5s
keyfile | `--keyfile` | Path to the SSL key file. |
keyfile_password | `--keyfile-password` | Password for the keyfile if the keyfile is password-protected. |
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
max_requests | `--max-requests` | Maximum number of requests a worker will process before restarting. |
max_requests_jitter | `--max-requests-jitter` | This jitter causes the max-requests per worker to be randomized by `randint(0, max_requests_jitter)` | 0
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