CherryPy is a pythonic, object-oriented HTTP framework.

CherryPy consists of not one, but four separate API layers.

The APPLICATION LAYER is the simplest. CherryPy applications are written as a tree of classes and methods, where each branch in the tree corresponds to a branch in the URL path. Each method is a ‘page handler’, which receives GET and POST params as keyword arguments, and returns or yields the (HTML) body of the response. The special method name ‘index’ is used for paths that end in a slash, and the special method name ‘default’ is used to handle multiple paths via a single handler. This layer also includes:

  • the ‘exposed’ attribute (and cherrypy.expose)
  • cherrypy.quickstart()
  • _cp_config attributes
  • (including cherrypy.session)
  • cherrypy.url()

The ENVIRONMENT LAYER is used by developers at all levels. It provides information about the current request and response, plus the application and server environment, via a (default) set of top-level objects:

  • cherrypy.request
  • cherrypy.response
  • cherrypy.engine
  • cherrypy.server
  • cherrypy.tree
  • cherrypy.config
  • cherrypy.thread_data
  • cherrypy.log
  • cherrypy.HTTPError, NotFound, and HTTPRedirect
  • cherrypy.lib

The EXTENSION LAYER allows advanced users to construct and share their own plugins. It consists of:

  • Hook API
  • Tool API
  • Toolbox API
  • Dispatch API
  • Config Namespace API

Finally, there is the CORE LAYER, which uses the core API’s to construct the default components which are available at higher layers. You can think of the default components as the ‘reference implementation’ for CherryPy. Megaframeworks (and advanced users) may replace the default components with customized or extended components. The core API’s are:

  • Application API
  • Engine API
  • Request API
  • Server API

These API’s are described in the CherryPy specification.


class cherrypy.HTTPError(status=500, message=None)

Exception used to return an HTTP error code (4xx-5xx) to the client.

This exception can be used to automatically send a response using a http status code, with an appropriate error page. It takes an optional status argument (which must be between 400 and 599); it defaults to 500 (“Internal Server Error”). It also takes an optional message argument, which will be returned in the response body. See RFC2616 for a complete list of available error codes and when to use them.


raise cherrypy.HTTPError(403)
raise cherrypy.HTTPError(
    "403 Forbidden", "You are not allowed to access this resource.")
code = None

The integer HTTP status code.

reason = None

The HTTP Reason-Phrase string.


Modify cherrypy.response status, headers, and body to represent self.

CherryPy uses this internally, but you can also use it to create an HTTPError object and set its output without raising the exception.

status = None

The HTTP status code. May be of type int or str (with a Reason-Phrase).

class cherrypy.HTTPRedirect(urls, status=None, encoding=None)

Exception raised when the request should be redirected.

This exception will force a HTTP redirect to the URL or URL’s you give it. The new URL must be passed as the first argument to the Exception, e.g., HTTPRedirect(newUrl). Multiple URLs are allowed in a list. If a URL is absolute, it will be used as-is. If it is relative, it is assumed to be relative to the current cherrypy.request.path_info.

If one of the provided URL is a unicode object, it will be encoded using the default encoding or the one passed in parameter.

There are multiple types of redirect, from which you can select via the status argument. If you do not provide a status arg, it defaults to 303 (or 302 if responding with HTTP/1.0).


raise cherrypy.HTTPRedirect("")
raise cherrypy.HTTPRedirect("/abs/path", 307)
raise cherrypy.HTTPRedirect(["path1", "path2?a=1&b=2"], 301)

See Redirecting POST for additional caveats.

encoding = 'utf-8'

The encoding when passed urls are not native strings


Modify cherrypy.response status, headers, and body to represent self.

CherryPy uses this internally, but you can also use it to create an HTTPRedirect object and set its output without raising the exception.

status = None

The integer HTTP status code to emit.

urls = None

The list of URL’s to emit.

class cherrypy.InternalRedirect(path, query_string='')

Exception raised to switch to the handler for a different URL.

This exception will redirect processing to another path within the site (without informing the client). Provide the new path as an argument when raising the exception. Provide any params in the querystring for the new URL.

class cherrypy.NotFound(path=None)

Exception raised when a URL could not be mapped to any handler (404).

This is equivalent to raising HTTPError("404 Not Found").

class cherrypy.CherryPyException

A base class for CherryPy exceptions.

class cherrypy.TimeoutError

Exception raised when Response.timed_out is detected.


cherrypy.expose(func=None, alias=None)

Expose the function, optionally providing an alias or set of aliases.


A site-wide LogManager; routes to app.log or global log as appropriate.

This LogManager implements cherrypy.log() and cherrypy.log.access(). If either function is called during a request, the message will be sent to the logger for the current Application. If they are called outside of a request, the message will be sent to the site-wide logger.

cherrypy.quickstart(root=None, script_name='', config=None)

Mount the given root, start the builtin server (and engine), then block.

root: an instance of a “controller class” (a collection of page handler
methods) which represents the root of the application.
script_name: a string containing the “mount point” of the application.

This should start with a slash, and be the path portion of the URL at which to mount the given root. For example, if root.index() will handle requests to “”, then the script_name argument would be “/dept/app1”.

It MUST NOT end in a slash. If the script_name refers to the root of the URI, it MUST be an empty string (not “/”).

config: a file or dict containing application config. If this contains
a [global] section, those entries will be used in the global (site-wide) config.
cherrypy.url(path='', qs='', script_name=None, base=None, relative=None)

Create an absolute URL for the given path.

If ‘path’ starts with a slash (‘/’), this will return
(base + script_name + path + qs).
If it does not start with a slash, this returns
(base + script_name [+ request.path_info] + path + qs).

If script_name is None, cherrypy.request will be used to find a script_name, if available.

If base is None, cherrypy.request.base will be used (if available). Note that you can use to change this.

Finally, note that this function can be used to obtain an absolute URL for the current request path (minus the querystring) by passing no args. If you call url(qs=cherrypy.request.query_string), you should get the original browser URL (assuming no internal redirections).

If relative is None or not provided, will be used (if available, else False). If False, the output will be an absolute URL (including the scheme, host, vhost, and script_name). If True, the output will instead be a URL that is relative to the current request path, perhaps including ‘..’ atoms. If relative is the string ‘server’, the output will instead be a URL that is relative to the server root; i.e., it will start with a slash.