Install & Compatibility
Where this runs
tested against v11.1.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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.225s · 19.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.201s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Server
✓ from cheroot.wsgi import Server
The core WSGI Server class is located within the `cheroot.wsgi` module.
PathInfoDispatcher
✓ from cheroot.wsgi import PathInfoDispatcher
Used for routing multiple WSGI applications based on URL path.
This quickstart demonstrates how to set up a basic Cheroot WSGI server with two different applications dispatched by `PathInfoDispatcher`. It listens on a configurable host and port (defaulting to `127.0.0.1:8070`), and handles incoming requests with a simple 'Hello, Cheroot!' response or a delayed response.
import os
import time
from cheroot.wsgi import Server, PathInfoDispatcher
def simple_app(environ, start_response):
"""A simple WSGI application."""
status = '200 OK'
headers = [('Content-type', 'text/plain')]
start_response(status, headers)
return [b'Hello, Cheroot!\n']
def delayed_app(environ, start_response):
"""An application with a delay to demonstrate concurrency."""
time.sleep(2) # Simulate work
status = '200 OK'
headers = [('Content-type', 'text/plain')]
start_response(status, headers)
return [b'Hello after 2 seconds!\n']
# Map paths to WSGI applications
path_map = {
'/': simple_app,
'/delay': delayed_app,
}
dispatcher = PathInfoDispatcher(path_map)
# Configure the server
# Default host is 0.0.0.0, default port is 8080 if not specified
# Using 127.0.0.1 and a common testing port here
host = os.environ.get('CHERoot_HOST', '127.0.0.1')
port = int(os.environ.get('CHERoot_PORT', 8070))
server = Server((host, port), dispatcher)
print(f"Cheroot server starting on http://{host}:{port}/")
print("Access http://localhost:8070/ and http://localhost:8070/delay")
print("Press Ctrl+C to stop...")
try:
server.start()
except KeyboardInterrupt:
server.stop()
print("Cheroot server stopped.")
Debug
Known issues
gotchaWhen serving WSGI applications, ensure that response status and headers adhere to PEP 3333. For Python 3, these must be `str` type but restricted to Latin-1 code points, not arbitrary Unicode.fixEnsure WSGI application returns `str` for status and headers with only Latin-1 compatible characters, and `bytes` for the body.
affects: All versions on Python 3
gotchaThe `start_response` callable in a WSGI application must not transmit headers immediately. It should store them, and the server (Cheroot) will transmit them only after the first non-empty iterable yielded by the application or explicit `write()` call.fixFollow the WSGI specification (PEP 3333) for `start_response` implementation in your application.
affects: All versions
gotchaBy default, if the host specification is omitted during server instantiation, Cheroot will listen on all IPv4 interfaces (`0.0.0.0`). The default port, if not specified, is `8080`. Always explicitly configure the bind address for production environments.fixAlways pass a `bind_addr` tuple like `('127.0.0.1', 8080)` or `('0.0.0.0', 80)` to the `Server` constructor, or use environment variables for flexible deployment. affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cheroot'
This error occurs because the 'cheroot' package is not installed in the Python environment, or it is not accessible from where the application is being run.
fixInstall the cheroot package using pip: `pip install cheroot`
ImportError: No module named 'cheroot.server'
This error typically means that while a version of Cheroot might be installed, the specific `cheroot.server` submodule cannot be found, possibly due to an outdated installation or an incorrect import path after a version change.
fixEnsure the latest version of cheroot is installed: `pip install --upgrade cheroot`. If using an older framework like CherryPy that bundles cheroot, ensure both are up-to-date or explicitly install cheroot as a standalone dependency.
socket.timeout: The write operation timed out.
This error indicates that the server failed to write data to a client socket within the configured timeout period, often due to a slow client connection, a large response, or the client disconnecting prematurely.
fixIncrease the `socket_timeout` configuration value for the Cheroot server, or ensure the network conditions allow for timely data transfer. For example, when using it with CherryPy, you might set `cherrypy.server.socket_timeout = 60`.
NoSSLError: Exception raised when a client speaks HTTP to an HTTPS socket.
This exception is raised by Cheroot when a client attempts to establish an unencrypted HTTP connection to a socket that has been configured to expect an encrypted HTTPS connection.
fixEnsure that clients connect using the correct protocol (HTTPS for an HTTPS-enabled Cheroot server) or configure separate HTTP and HTTPS endpoints if both protocols are required.
ConnectionRefusedError: [Errno 111] Connection refused
This common network error occurs when a client tries to connect to a Cheroot server (or any network service), but the server is not running, not listening on the specified address/port, or a firewall is blocking the connection.
fixVerify that the Cheroot server is running, listening on the expected host and port (e.g., `0.0.0.0:8000`), and that no firewall is blocking the incoming connection to that port.
Upgrade
Version history
11.1.2latest on PyPI · released Nov 7, 2025
Audit
Dependencies
zope.interfaceoptionalRequired for the optional 'zope' extra, which might be used for specific interface implementations or compatibility.