Usage

The following code will run waitress on port 8080 on all available IP addresses, both IPv4 and IPv6.

from waitress import serve
serve(wsgiapp, listen='*:8080')

Press Ctrl-C (or Ctrl-Break on Windows) to exit the server.

The following will run waitress on port 8080 on all available IPv4 addresses, but not IPv6.

from waitress import serve
serve(wsgiapp, host='0.0.0.0', port=8080)

By default Waitress binds to any IPv4 address on port 8080. You can omit the host and port arguments and just call serve with the WSGI app as a single argument:

from waitress import serve
serve(wsgiapp)

If you want to serve your application through a UNIX domain socket (to serve a downstream HTTP server/proxy such as nginx, lighttpd, and so on), call serve with the unix_socket argument:

from waitress import serve
serve(wsgiapp, unix_socket='/path/to/unix.sock')

Needless to say, this configuration won't work on Windows.

Exceptions generated by your application will be shown on the console by default. See Access Logging to change this.

There's an entry point for PasteDeploy (egg:waitress#main) that lets you use Waitress's WSGI gateway from a configuration file, e.g.:

[server:main]
use = egg:waitress#main
listen = 127.0.0.1:8080

Using host and port is also supported:

[server:main]
host = 127.0.0.1
port = 8080

The PasteDeploy syntax for UNIX domain sockets is analagous:

[server:main]
use = egg:waitress#main
unix_socket = /path/to/unix.sock

You can find more settings to tweak (arguments to waitress.serve or equivalent settings in PasteDeploy) in Arguments to waitress.serve.

Additionally, there is a command line runner called waitress-serve, which can be used in development and in situations where the likes of PasteDeploy is not necessary:

# Listen on both IPv4 and IPv6 on port 8041
waitress-serve --listen=*:8041 myapp:wsgifunc

# Listen on only IPv4 on port 8041
waitress-serve --port=8041 myapp:wsgifunc

Heroku

Waitress can be used to serve WSGI apps on Heroku, include waitress in your requirements.txt file a update the Procfile as following:

web: waitress-serve \
    --listen "*:$PORT" \
    --trusted-proxy '*' \
    --trusted-proxy-headers 'x-forwarded-for x-forwarded-proto x-forwarded-port' \
    --log-untrusted-proxy-headers \
    --clear-untrusted-proxy-headers \
    --threads ${WEB_CONCURRENCY:-4} \
    myapp:wsgifunc

The proxy config informs Waitress to trust the forwarding headers set by the Heroku load balancer. It also allows for setting the standard WEB_CONCURRENCY environment variable to tweak the number of requests handled by Waitress at a time.

Note that Waitress uses a thread-based model and careful effort should be taken to ensure that requests do not take longer than 30 seconds or Heroku will inform the client that the request failed even though the request is still being processed by Waitress and occupying a thread until it completes.

For more information on this, see waitress-serve.