waitress

library3.0.2pypypi✓ verified 26d ago

Waitress is a production-quality pure-Python WSGI server with a focus on simplicity and reliability. It's actively maintained by the Pylons Project, receiving frequent updates to support new Python versions and address security concerns. The current version is 3.0.2.

web-framework http-networking

pip install waitress

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · WAITRESS

waitress

web-frameworkpythonv3.0.2

Install

1.5s avg

Import

76ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.084s · 18.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.068s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

serve

✓ from waitress import serve

The primary function to start the WSGI server.

This example demonstrates how to serve a minimal WSGI application using Waitress. It defines a simple WSGI callable `simple_app` and then uses `waitress.serve()` to run it on `127.0.0.1:8080`.

from waitress import serve def simple_app(environ, start_response): """A barebones WSGI application.""" status = '200 OK' headers = [('Content-type', 'text/plain; charset=utf-8')] start_response(status, headers) return [b"Hello from Waitress!"] if __name__ == '__main__': print("Serving on http://127.0.0.1:8080") serve(simple_app, host='127.0.0.1', port=8080)

waitress-serve --version

Debug

Known issues

breakingWaitress dropped support for Python 3.8 starting with version 3.0.1. Running on Python 3.8 or older will result in errors.

fix

Upgrade your Python environment to 3.9 or newer. Python 3.13 is supported from v3.0.1.

affects: 3.0.1+

breakingWaitress v3.0.2 changed how `trusted_proxy_headers` are handled for security. Untrusted values from proxy headers are now dropped, and Waitress *updates* the headers passed to the WSGI app with validated values. Applications might receive different, more secure header values than before, potentially breaking logic that relied on previously available, untrusted headers.

fix

Review your application's reliance on `X-Forwarded-For`, `X-Forwarded-Proto`, etc. when `trusted_proxy_headers` is enabled. Ensure your proxy configuration and application logic are compatible with Waitress's new, stricter header processing.

affects: 3.0.2+

breakingStarting with version 3.0.0, Waitress performs stricter validation of HTTP request methods and versions according to RFCs. Malformed requests that previously might have passed through could now be rejected with a 400 Bad Request.

fix

Ensure client requests adhere to HTTP/1.0 or HTTP/1.1 specifications for methods and versions. Clients sending non-standard or malformed requests may need updates.

affects: 3.0.0+

gotchaWaitress binds to `127.0.0.1` (localhost) by default. If you need to serve the application on a network interface accessible from other machines (e.g., in a Docker container or a public server), you must explicitly set the `host` parameter.

fix

When calling `waitress.serve()`, pass `host='0.0.0.0'` (to bind to all available public interfaces) or the specific public IP address you want to bind to, e.g., `serve(app, host='0.0.0.0', port=8080)`.

affects: all

Errors

Common errors & fixes

ImportError: cannot import name 'serve' from 'waitress'

This error occurs when the script is named 'waitress.py', causing a conflict with the actual Waitress module.

fix

Rename your script to avoid naming conflicts, e.g., 'app_server.py'.

SyntaxError: invalid syntax

This error can occur due to an outdated 'python-dateutil' package incompatible with the current Python version.

fix

Upgrade 'python-dateutil' to the latest version using 'pip install --upgrade python-dateutil'.

Error: Bad module 'cardisle'

This error indicates that Waitress cannot import the specified module, often due to incorrect module paths or names.

fix

Ensure the module path is correct and accessible, and verify the module name is spelled correctly.

System.Net.WebException: The operation has timed out

This error occurs when the Waitress server hangs, leading to timeout errors in client applications.

fix

Increase the number of threads in Waitress to handle more concurrent requests, e.g., 'serve(app, threads=4)'.

Error: Bad object name 'application'

This error occurs when Waitress cannot find the specified WSGI application object.

fix

Ensure the WSGI application object is correctly defined and accessible in your module.

Upgrade

Version history

3.0.2latest on PyPI · released Nov 16, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Pylons/waitress ↗

packagehttps://pypi.org/project/waitress/ ↗

docshttps://docs.pylonsproject.org/projects/waitress/en/latest/index.html ↗

changeloghttps://docs.pylonsproject.org/projects/waitress/en/latest/index.html#change-history ↗