waitress-serve

Run a Python web app

$ waitress-serve [import.path:wsgi_func]

$ waitress-serve --listen=[localhost]:[8080] [import.path:wsgi_func]

$ waitress-serve --unix-socket=[path/to/socket] [import.path:wsgi_func]

$ waitress-serve --threads=[4] [import.path:wsgifunc]

$ waitress-serve --call [import.path.wsgi_factory]

$ waitress-serve --url-scheme=[https] [import.path:wsgi_func]

waitress-serve [OPTIONS] MODULE:APPLICATION
waitress-serve [OPTIONS] --call MODULE:CALLABLE

MODULE:APPLICATION
    Specifies the Python module and the WSGI application object within it (e.g., myproject.wsgi:application).

--call MODULE:CALLABLE
    Invokes a Python callable (function or method) within the specified module, which is expected to return the WSGI application object.

--host HOST
    Optional. The hostname or IP address the server should listen on. Defaults to 0.0.0.0 (all available interfaces).

--port PORT
    Optional. The TCP port the server should listen on. Defaults to 8080.

--unix-socket PATH
    Optional. Specifies a path to a Unix domain socket for listening, instead of TCP host/port.

--threads COUNT
    Optional. The number of threads Waitress will use to handle requests. Defaults to 4.

--url-prefix PREFIX
    Optional. A URL prefix to prepend to the application's paths. Useful when serving the app under a subpath.

--ident IDENT
    Optional. A string to use for server identification in HTTP headers (e.g., Server: Waitress-ident).

--recv-bytes COUNT
    Optional. Maximum number of bytes to receive in one go.

--send-bytes COUNT
    Optional. Maximum number of bytes to send in one go.

--trusted-proxy IP_ADDRESSES
    Optional. Comma-separated list of trusted proxy IP addresses.

--trusted-proxy-headers HEADERS
    Optional. Comma-separated list of headers to trust from trusted proxies (e.g., X-Forwarded-For).

--log-file PATH
    Optional. Path to a file for logging.

--version
    Displays the Waitress version and exits.

--help
    Displays a help message with available options and exits.

waitress-serve is the command-line utility for Waitress, a production-quality, pure-Python Web Server Gateway Interface (WSGI) server. It's designed to be simple, fast, and robust, providing a reliable way to serve Python web applications. Unlike complex servers, Waitress focuses solely on the WSGI protocol, making it ideal for microservices and small to medium-sized applications. It's written entirely in Python, has no external dependencies, and is cross-platform. Developers use waitress-serve to launch their WSGI-compatible applications, specifying the Python module and application object to be served, along with configuration options like host, port, and thread count. While capable of standalone operation, it's frequently deployed behind a reverse proxy like Nginx or Apache for enhanced security, load balancing, and static file serving.

Installation Required: waitress-serve is not a standard Linux command. It requires Python to be installed, and the Waitress package must be installed via pip (e.g., pip install waitress).
WSGI Focus: It is designed exclusively for serving WSGI applications and does not directly handle static files or act as a reverse proxy. For production environments, it's highly recommended to use a dedicated web server like Nginx or Apache in front of Waitress for static file serving, SSL termination, and advanced routing.
Single Process: By default, Waitress runs as a single process with multiple threads. For higher concurrency or fault tolerance, consider using process managers or multiple Waitress instances with a load balancer.

For production deployments, it's strongly advised to place waitress-serve behind a reverse proxy (e.g., Nginx, Apache). The proxy can handle SSL termination, serve static assets directly (which Waitress is not optimized for), manage rate limiting, and provide load balancing across multiple Waitress instances.

While waitress-serve can be fully configured via command-line options, it can also integrate with PasteDeploy configuration files (often paste.ini or development.ini). This allows for more complex, environment-specific configurations to be managed outside the command line.

Waitress was developed by the Pylons Project as a simple, high-quality, and robust WSGI server written entirely in Python. Its development was driven by the need for a pure-Python server that was easy to deploy and had minimal external dependencies, making it an attractive option for projects that prefer to avoid complex build requirements or system-specific binaries. Since its inception, it has gained popularity for its reliability and ease of use, particularly in environments where a lightweight, production-ready WSGI server is needed without the overhead of larger, feature-rich alternatives. It continues to be actively maintained and is a staple in many Python web application deployments.

gunicorn(1), uwsgi(1), nginx(8), apache2(8), python(1), pip(1)