Beaker can be configured several different ways, depending on how it is to be used. The most recommended style is to use a dictionary of preferences that are to be passed to either the SessionMiddleware or the CacheManager.

Since both Beaker’s sessions and caching use the same back-end container storage system, there’s some options that are applicable to both of them in addition to session and cache specific configuration.

Most options can be specified as a string (necessary to config options that are setup in INI files), and will be coerced to the appropriate value. Only datetime’s and timedelta’s cannot be coerced and must be the actual objects.

Frameworks using Beaker usually allow both caching and sessions to be configured in the same spot, Beaker assumes this condition as well and requires options for caching and sessions to be prefixed appropriately.

For example, to configure the cookie_expires option for Beaker sessions below, an appropriate entry in a Pylons INI file would be:

# Setting cookie_expires = true causes Beaker to omit the
# expires= field from the Set-Cookie: header, signaling the cookie
# should be discarded when the browser closes.
beaker.session.cookie_expires = true


When using the options in a framework like Pylons or TurboGears2, these options must be prefixed by beaker., for example in a Pylons INI file:

beaker.session.data_dir = %(here)s/data/sessions/data
beaker.session.lock_dir = %(here)s/data/sessions/lock

Or when using stand-alone with the SessionMiddleware:

from beaker.middleware import SessionMiddleware

session_opts = {
    'session.cookie_expires': True

app = SomeWSGIAPP()
app = SessionMiddleware(app, session_opts)

Or when using the CacheManager:

from beaker.cache import CacheManager
from beaker.util import parse_cache_config_options

cache_opts = {
    'cache.type': 'file',
    'cache.data_dir': '/tmp/cache/data',
    'cache.lock_dir': '/tmp/cache/lock'

cache = CacheManager(**parse_cache_config_options(cache_opts))


When using the CacheManager directly, all dict options must be run through the beaker.util.parse_cache_config_options() function to ensure they’re valid and of the appropriate type.

Options For Sessions and Caching

data_dir (optional, string)
Used with any back-end that stores its data in physical files, such as the dbm or file-based back-ends. This path should be an absolute path to the directory that stores the files.
lock_dir (required, string)
Used with every back-end, to coordinate locking. With caching, this lock file is used to ensure that multiple processes/threads aren’t attempting to re-create the same value at the same time (The Dog-Pile Effect)
memcache_module (optional, string)
One of the names memcache, cmemcache, pylibmc, or auto. Default is auto. Specifies which memcached client library should be imported when using the ext:memcached backend. If left at its default of auto, pylibmc is favored first, then cmemcache, then memcache. New in 1.5.5.
type (required, string)

The name of the back-end to use for storing the sessions or cache objects.

Available back-ends supplied with Beaker: file, dbm, memory, ext:memcached, ext:database, ext:google

For sessions, the additional type of cookie is available which will store all the session data in the cookie itself. As such, size limitations apply (4096 bytes).

Some of these back-ends require the url option as listed below.

webtest_varname (optional, string)
The name of the attribute to use when stashing the session object into the environ for use with WebTest. The name provided here is where the session object will be attached to the WebTest TestApp return value.
url (optional, string)

URL is specific to use of either ext:memcached or ext:database. When using one of those types, this option is required.

When used with ext:memcached, this should be either a single, or semi-colon separated list of memcached servers:

session_opts = {
    'session.type': 'ext:memcached',
    'session.url': '',

When used with ext:database, this should be a valid SQLAlchemy database string.

Session Options

The Session handling takes a variety of additional options relevant to how it stores session id’s in cookies, and when using the optional encryption.

auto (optional, bool)

When set to True, the session will save itself anytime it is accessed during a request, negating the need to issue the save() method.

Defaults to False.

cookie_expires (optional, bool, datetime, timedelta, int)

Determines when the cookie used to track the client-side of the session will expire. When set to a boolean value, it will either expire at the end of the browsers session, or never expire.

Setting to a datetime forces a hard ending time for the session (generally used for setting a session to a far off date).

Setting to an integer will result in the cookie being set to expire in that many seconds. I.e. a value of 300 will result in the cookie being set to expire in 300 seconds.

Defaults to never expiring.

Encryption Options

These options should then be used instead of the secret option when a cookie only session is used and together with the secret option when a server side session is used.

encrypt_key (required, string)
Encryption key to use for the AES cipher. This should be a fairly long randomly generated string.
validate_key (required, string)
Validation key used to sign the AES encrypted data.
crypto_type (optional, string)

Encryption backend to use. If default is used, one of the installed backends is picked.

Other valid choices are cryptography, nss, pycrypto.


You may need to install additional libraries to use Beaker’s cookie-based session encryption. See the Encryption section for more information.

Cache Options

For caching, options may be directly specified on a per-use basis with the cache() decorator, with the rest of these options used as fallback should one of them not be specified in the call.

Only the lock_dir option is strictly required, unless using the file-based back-ends as noted with the sessions.

expire (optional, integer)
Seconds until the cache is considered old and a new value is created.

Cache Region Options

Starting in Beaker 1.3, cache regions are now supported. These can be thought of as bundles of configuration options to apply, rather than specifying the type and expiration on a per-usage basis.

enabled (optional, bool)

Quick toggle to disable or enable caching across an entire application.

This should generally be used when testing an application or in development when caching should be ignored.

Defaults to True.

regions (optional, list, tuple)

Names of the regions that are to be configured.

For each region, all of the other cache options are valid and will be read out of the cache options for that key. Options that are not listed under a region will be used globally in the cache unless a region specifies a different value.

For example, to specify two batches of options, one called long-term, and one called short-term:

cache_opts = {
    'cache.data_dir': '/tmp/cache/data',
    'cache.lock_dir': '/tmp/cache/lock'
    'cache.regions': 'short_term, long_term',
    'cache.short_term.type': 'ext:memcached',
    'cache.short_term.url': '',
    'cache.short_term.expire': '3600',
    'cache.long_term.type': 'file',
    'cache.long_term.expire': '86400',