The CherryPy Engine

The cherrypy.engine object contains and manages site-wide behavior: daemonization, HTTP server start/stop, process reload, signal handling, drop privileges, PID file management, logging for all of these, and many more.

Any task that needs to happen outside of the request process is managed by the Engine via Plugins. You can add your own site-wide behaviors, too; see Custom Plugins. The Engine handles these tasks whether you start your site from a script, from an external server process like Apache, or via cherryd.

State Management

The Engine manages the state of the site. Engine methods like cherrypy.engine.start move it from one state to another:

   A   A         |
   |    \___     |
   |        \    |
   |         V   V

Note in particular that the Engine allows you to stop and restart it again without stopping the process. This can be used to build highly dynamic sites, and is invaluable for debugging live servers.


The Engine uses topic-based publish-subscribe messaging to manage event-driven behaviors like autoreload and daemonization. When the Engine moves from one state to another, it publishes a message on a channel named after the activity. For example, when you call cherrypy.engine.start, the Engine moves from the STOPPED state to the STARTING state, publishes a message on the “start” channel, and then moves to the STARTED state.


Engine Plugins package up channel listeners into easy-to-use components.

Engine Plugins have a subscribe method which you can use to “turn them on”; that is, they will start listening for messages published on event channels. For example, to turn on PID file management:

from cherrypy.process.plugins import PIDFile
p = PIDFile(cherrypy.engine, "/var/run/")

If you want to turn off a plugin, call p.unsubscribe().

The following builtin plugins are subscribed by default: