Waitress is meant to be a production-quality pure-Python WSGI server with very acceptable performance. It has no dependencies except ones which live in the Python standard library. It runs on CPython on Unix and Windows under Python 2.7+ and Python 3.3+. It is also known to run on PyPy 1.6.0 on UNIX. It supports HTTP/1.0 and HTTP/1.1.
Here's normal usage of the server:
from waitress import serve
serve(wsgiapp, listen='*:8080')This will run waitress on port 8080 on all available IP addresses, both IPv4 and IPv6.
from waitress import serve
serve(wsgiapp, host='0.0.0.0', port=8080)This will run waitress on port 8080 on all available IPv4 addresses.
If you want to serve your application on all IP addresses, 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)Press Ctrl-C (or Ctrl-Break on Windows) to exit the server.
The default is to bind to any IPv4 address on port 8080:
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, e.g. nginx, lighttpd, etc.), 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 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:8080Using host and port is also supported:
[server:main]
host = 127.0.0.1
port = 8080The PasteDeploy syntax for UNIX domain sockets is analagous:
[server:main]
use = egg:waitress#main
unix_socket = /path/to/unix.sockYou can find more settings to tweak (arguments to waitress.serve or equivalent settings in PasteDeploy) in arguments.
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:wsgifuncFor more information on this, see runner.
waitress.serve calls logging.basicConfig() to set up logging to the console when the server starts up. Assuming no other logging configuration has already been done, this sets the logging default level to logging.WARNING. The Waitress logger will inherit the root logger's level information (it logs at level WARNING or above).
Waitress sends its logging output (including application exception renderings) to the Python logger object named waitress. You can influence the logger level and output stream using the normal Python logging module API. For example:
import logging
logger = logging.getLogger('waitress')
logger.setLevel(logging.INFO)Within a PasteDeploy configuration file, you can use the normal Python logging module .ini file format to change similar Waitress logging options. For example:
[logger_waitress]
level = INFOOften people will set up "pure Python" web servers behind reverse proxies, especially if they need SSL support (Waitress does not natively support SSL). Even if you don't need SSL support, it's not uncommon to see Waitress and other pure-Python web servers set up to "live" behind a reverse proxy; these proxies often have lots of useful deployment knobs.
If you're using Waitress behind a reverse proxy, you'll almost always want your reverse proxy to pass along the Host header sent by the client to Waitress, in either case, as it will be used by most applications to generate correct URLs.
For example, when using Nginx as a reverse proxy, you might add the following lines in a location section:
proxy_set_header Host $host;The Apache directive named ProxyPreserveHost does something similar when used as a reverse proxy.
Unfortunately, even if you pass the Host header, the Host header does not contain enough information to regenerate the original URL sent by the client. For example, if your reverse proxy accepts HTTPS requests (and therefore URLs which start with https://), the URLs generated by your application when used behind a reverse proxy served by Waitress might inappropriately be http://foo rather than https://foo. To fix this, you'll want to change the wsgi.url_scheme in the WSGI environment before it reaches your application. You can do this in one of three ways:
- You can pass a
url_schemeconfiguration variable to thewaitress.servefunction. - You can configure the proxy reverse server to pass a header,
X_FORWARDED_PROTO, whose value will be set for that request as thewsgi.url_schemeenvironment value. Note that you must also conigurewaitress.serveby passing the IP address of that proxy as itstrusted_proxy. - You can use Paste's
PrefixMiddlewarein conjunction with configuration settings on the reverse proxy server.
You can have the Waitress server use the https url scheme by default.:
from waitress import serve
serve(wsgiapp, listen='0.0.0.0:8080', url_scheme='https')This works if all URLs generated by your application should use the https scheme.
If your proxy accepts both HTTP and HTTPS URLs, and you want your application to generate the appropriate url based on the incoming scheme, also set up your proxy to send a X-Forwarded-Proto with the original URL scheme along with each proxied request. For example, when using Nginx:
proxy_set_header X-Forwarded-Proto $scheme;or via Apache:
RequestHeader set X-Forwarded-Proto httpsNote
You must also configure the Waitress server's trusted_proxy to contain the IP address of the proxy in order for this header to override the default URL scheme.
You can have the Waitress server use a particular url prefix by default for all URLs generated by downstream applications that take SCRIPT_NAME into account.:
from waitress import serve
serve(wsgiapp, listen='0.0.0.0:8080', url_prefix='/foo')Setting this to any value except the empty string will cause the WSGI SCRIPT_NAME value to be that value, minus any trailing slashes you add, and it will cause the PATH_INFO of any request which is prefixed with this value to be stripped of the prefix. This is useful in proxying scenarios where you wish to forward all traffic to a Waitress server but need URLs generated by downstream applications to be prefixed with a particular path segment.
If only some of the URLs generated by your application should use the https scheme (and some should use http), you'll need to use Paste's PrefixMiddleware as well as change some configuration settings on your proxy. To use PrefixMiddleware, wrap your application before serving it using Waitress:
from waitress import serve
from paste.deploy.config import PrefixMiddleware
app = PrefixMiddleware(app)
serve(app)Once you wrap your application in the the PrefixMiddleware, the middleware will notice certain headers sent from your proxy and will change the wsgi.url_scheme and possibly other WSGI environment variables appropriately.
Once your application is wrapped by the prefix middleware, you should instruct your proxy server to send along the original Host header from the client to your Waitress server, as well as sending along a X-Forwarded-Proto header with the appropriate value for wsgi.url_scheme.
If your proxy accepts both HTTP and HTTPS URLs, and you want your application to generate the appropriate url based on the incoming scheme, also set up your proxy to send a X-Forwarded-Proto with the original URL scheme along with each proxied request. For example, when using Nginx:
proxy_set_header X-Forwarded-Proto $scheme;It's permitted to set an X-Forwarded-For header too; the PrefixMiddleware uses this to adjust other environment variables (you'll have to read its docs to find out which ones, I don't know what they are). For the X-Forwarded-For header:
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;Note that you can wrap your application in the PrefixMiddleware declaratively in a PasteDeploy configuration file too, if your web framework uses PasteDeploy-style configuration:
[app:myapp]
use = egg:mypackage#myapp
[filter:paste_prefix]
use = egg:PasteDeploy#prefix
[pipeline:main]
pipeline =
paste_prefix
myapp
[server:main]
use = egg:waitress#main
listen = 127.0.0.1:8080Note that you can also set PATH_INFO and SCRIPT_NAME using PrefixMiddleware too (its original purpose, really) instead of using Waitress' url_prefix adjustment. See the PasteDeploy docs for more information.
design.rst differences.rst api.rst arguments.rst filewrapper.rst runner.rst glossary.rst
- Does not support SSL natively.
The Pylons Project web site is the main online source of Waitress support and development information.
To report bugs, use the issue tracker.
If you've got questions that aren't answered by this documentation, contact the Pylons-devel maillist or join the #pyramid IRC channel.
Browse and check out tagged and trunk versions of Waitress via the Waitress GitHub repository. To check out the trunk via git, use this command:
git clone git@github.com:Pylons/waitress.gitTo find out how to become a contributor to Waitress, please see the contributor's section of the documentation.
At the time of the release of Waitress, there are already many pure-Python WSGI servers. Why would we need another?
Waitress is meant to be useful to web framework authors who require broad platform support. It's neither the fastest nor the fanciest WSGI server available but using it helps eliminate the N-by-M documentation burden (e.g. production vs. deployment, Windows vs. Unix, Python 3 vs. Python 2, PyPy vs. CPython) and resulting user confusion imposed by spotty platform support of the current (2012-ish) crop of WSGI servers. For example, gunicorn is great, but doesn't run on Windows. paste.httpserver is perfectly serviceable, but doesn't run under Python 3 and has no dedicated tests suite that would allow someone who did a Python 3 port to know it worked after a port was completed. wsgiref works fine under most any Python, but it's a little slow and it's not recommended for production use as it's single-threaded and has not been audited for security issues.
At the time of this writing, some existing WSGI servers already claim wide platform support and have serviceable test suites. The CherryPy WSGI server, for example, targets Python 2 and Python 3 and it can run on UNIX or Windows. However, it is not distributed separately from its eponymous web framework, and requiring a non-CherryPy web framework to depend on the CherryPy web framework distribution simply for its server component is awkward. The test suite of the CherryPy server also depends on the CherryPy web framework, so even if we forked its server component into a separate distribution, we would have still needed to backfill for all of its tests. The CherryPy team has started work on Cheroot, which should solve this problem, however.
Waitress is a fork of the WSGI-related components which existed in zope.server. zope.server had passable framework-independent test coverage out of the box, and a good bit more coverage was added during the fork. zope.server has existed in one form or another since about 2001, and has seen production usage since then, so Waitress is not exactly "another" server, it's more a repackaging of an old one that was already known to work fairly well.