Install & Compatibility
Where this runs
tested against v18.10.0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.538s · 37.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.1s · import 0.512s · 38MB
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cherrypy
✓ import cherrypy
The main module for accessing CherryPy's core functionalities, decorators, and server controls.
This minimal example demonstrates a 'Hello World' application. Define a class with a method (e.g., `index`) and decorate it with `@cherrypy.expose` to make it accessible via a URL. Then, start the CherryPy server using `cherrypy.quickstart()` with an instance of your application class.
import cherrypy
class HelloWorld(object):
@cherrypy.expose
def index(self):
return "Hello World!"
if __name__ == '__main__':
# By default, CherryPy binds to 127.0.0.1:8080 (localhost)
# To make it accessible from other machines, set 'server.socket_host' to '0.0.0.0'
# cherrypy.config.update({'server.socket_host': '0.0.0.0'})
cherrypy.quickstart(HelloWorld())
cherrypy --version
Debug
Known issues
breakingCherryPy 18.0.0 dropped support for Python 2.7 and Python 3.4. Users on these Python versions must use an older CherryPy version (e.g., CherryPy 17 LTS).fixUpgrade to Python 3.6 or newer, or pin CherryPy to a version < 18.0.0.
affects: >=18.0.0
breakingThe `basic_auth` and `digest_auth` tools, along with the `httpauth` module, were officially deprecated in v14.0.0 and subsequently removed in v16.0.0.fixMigrate to the newer `auth_basic` and `auth_digest` tools or implement custom authentication solutions.
affects: >=16.0.0
gotchaBy default, CherryPy's built-in HTTP server binds to `127.0.0.1` (localhost). This means your application is only accessible from the machine it's running on.fixTo make the application accessible from other network machines, update the server configuration: `cherrypy.config.update({'server.socket_host': '0.0.0.0'})`. affects: All versions
gotchaMethods intended to be exposed as web endpoints (accessible via URL) must be decorated with `@cherrypy.expose`. Forgetting this decorator will result in a 404 Not Found error for that URL path.fixAlways apply `@cherrypy.expose` to methods that should serve HTTP requests.
affects: All versions
breakingCheroot, CherryPy's underlying HTTP server, dropped support for Python 3.6 and 3.7, now requiring Python 3.8 or later as of its recent releases. While CherryPy itself states support up to 3.11, newer Cheroot versions might introduce a conflict for older Python environments.fixEnsure your Python environment is 3.8+ if using the latest Cheroot, or pin Cheroot to an older version compatible with Python 3.6/3.7 if necessary.
affects: CherryPy using recent Cheroot versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cherrypy'
The CherryPy library is not installed or not installed in the Python environment currently being used to run the application.
fixEnsure CherryPy is installed in your active Python environment by running: `pip install cherrypy`
AttributeError: module 'cherrypy' has no attribute 'expose'
This typically happens when a Python file in your project is named `cherrypy.py`, causing Python to import your local file instead of the actual CherryPy library.
fixRename your local `cherrypy.py` file to something else (e.g., `my_app.py`) and delete any `__pycache__` directories or `.pyc` files that might have been created.
cherrypy.process.wspbus.ChannelFailures: Timeout('Port XXXX not free on Y.Y.Y.Y.',)
The specified `socket_port` and `socket_host` for the CherryPy server are already in use by another application or process on your system, preventing CherryPy from binding to it.
fixChange the `server.socket_port` in your CherryPy configuration to an available port (e.g., 8081, 9000), or ensure no other process is using the desired port. You can configure it via `cherrypy.server.socket_port = 8080` in your code or in a config file.
AttributeError: CherryPy Tools cannot be turned on directly. Instead, turn them on via config, or use them as decorators on your page handlers.
CherryPy tools (like sessions, staticdir, etc.) must be enabled through configuration dictionaries or by using the `@cherrypy.tools.toolname()` decorator, not by directly assigning `True` to `cherrypy.tools.toolname.on` outside of a config context.
fixEnable tools using a configuration dictionary passed to `cherrypy.quickstart()` or `cherrypy.tree.mount()`, or set them via `cherrypy.config.update({'tools.sessions.on': True})`. NotFound: (404, "The path '/' was not found.")
This error occurs when CherryPy cannot find a suitable page handler for the requested URL, often because the root object is not correctly mounted or a method is not properly exposed.
fixEnsure your root class instance is correctly passed to `cherrypy.quickstart()` and that the methods intended to handle requests (like `index`) are decorated with `@cherrypy.expose`.
Upgrade
Version history
18.10.0latest on PyPI · released Jun 14, 2024
Audit
Dependencies
cherootrequiredHigh-performance, pure-Python HTTP server used by CherryPy.
magicbusrequiredProcess Bus for connecting components.
zc.lockfilerequiredUsed for session concurrency support.
pywin32optionalOptional dependency for Windows-specific features.