This document is for Celery's development version, which can be significantly different from previous releases. Get old docs here: 3.1.

Configuration and defaults

This document describes the configuration options available.

If you’re using the default loader, you must create the module and make sure it is available on the Python path.

Example configuration file

This is an example configuration file to get you started. It should contain all you need to run a basic Celery set-up.

## Broker settings.
broker_url = 'amqp://guest:guest@localhost:5672//'

# List of modules to import when celery starts.
imports = ('myapp.tasks',)

## Using the database to store task state and results.
result_backend = 'db+sqlite:///results.db'

task_annotations = {'tasks.add': {'rate_limit': '10/s'}}

New lowercase settings

Version 4.0 introduced new lower case settings and setting organization.

The major difference between previous versions, apart from the lower case names, are the renaming of some prefixes, like celerybeat_ to beat_, celeryd_ to worker_, and most of the top level celery_ settings have been moved into a new task_ prefix.

Celery will still be able to read old configuration files, so there is no rush in moving to the new settings format.

Setting name Replace with
ADMINS admins
SERVER_EMAIL server_email
CELERYBEAT_MAX_LOOP_INTERVAL beat_max_loop_interval
BROKER_URL broker_url
BROKER_TRANSPORT broker_transport
BROKER_TRANSPORT_OPTIONS broker_transport_options
BROKER_CONNECTION_TIMEOUT broker_connection_timeout
BROKER_CONNECTION_RETRY broker_connection_retry
BROKER_CONNECTION_MAX_RETRIES broker_connection_max_retries
BROKER_FAILOVER_STRATEGY broker_failover_strategy
BROKER_HEARTBEAT broker_heartbeat
BROKER_LOGIN_METHOD broker_login_method
BROKER_POOL_LIMIT broker_pool_limit
BROKER_USE_SSL broker_use_ssl
CELERY_CACHE_BACKEND_OPTIONS cache_backend_options
CASSANDRA_ENTRY_TTL cassandra_entry_ttl
CASSANDRA_KEYSPACE cassandra_keyspace
CASSANDRA_PORT cassandra_port
CASSANDRA_READ_CONSISTENCY cassandra_read_consistency
CASSANDRA_SERVERS cassandra_servers
CASSANDRA_WRITE_CONSISTENCY cassandra_write_consistency
CELERY_COUCHBASE_BACKEND_SETTINGS couchbase_backend_settings
EMAIL_HOST email_host
EMAIL_HOST_USER email_host_user
EMAIL_HOST_PASSWORD email_host_password
EMAIL_PORT email_port
EMAIL_TIMEOUT email_timeout
EMAIL_USE_SSL email_use_ssl
EMAIL_USE_TLS email_use_tls
CELERY_MONGODB_BACKEND_SETTINGS mongodb_backend_settings
CELERY_EVENT_QUEUE_EXPIRES event_queue_expires
CELERY_EVENT_QUEUE_TTL event_queue_ttl
CELERY_REDIS_MAX_CONNECTIONS redis_max_connections
CELERY_RESULT_EXCHANGE_TYPE result_exchange_type
CELERY_RESULT_DBURI sqlalchemy_dburi
CELERY_RESULT_ENGINE_OPTIONS sqlalchemy_engine_options
-*-_DB_SHORT_LIVED_SESSIONS sqlalchemy_short_lived_sessions
CELERY_RESULT_DB_TABLE_NAMES sqlalchemy_db_names
CELERY_SECURITY_CERT_STORE security_cert_store
CELERY_ACKS_LATE task_acks_late
CELERY_ALWAYS_EAGER task_always_eager
CELERY_ANNOTATIONS task_annotations
CELERY_CREATE_MISSING_QUEUES task_create_missing_queues
CELERY_DEFAULT_DELIVERY_MODE task_default_delivery_mode
CELERY_DEFAULT_EXCHANGE task_default_exchange
CELERY_DEFAULT_EXCHANGE_TYPE task_default_exchange_type
CELERY_DEFAULT_QUEUE task_default_queue
CELERY_DEFAULT_RATE_LIMIT task_default_rate_limit
CELERY_DEFAULT_ROUTING_KEY task_default_routing_key
-"-_EAGER_PROPAGATES_EXCEPTIONS task_eager_propagates
CELERY_IGNORE_RESULT task_ignore_result
CELERY_TASK_PUBLISH_RETRY task_publish_retry
CELERY_TASK_PUBLISH_RETRY_POLICY task_publish_retry_policy
CELERY_QUEUES task_queues
CELERY_ROUTES task_routes
CELERY_SEND_TASK_ERROR_EMAILS task_send_error_emails
CELERY_SEND_TASK_SENT_EVENT task_send_sent_event
CELERYD_TASK_SOFT_TIME_LIMIT task_soft_time_limit
CELERY_TRACK_STARTED task_track_started
CELERYD_AGENT worker_agent
CELERYD_AUTOSCALER worker_autoscaler
CELERYD_AUTORELAODER worker_autoreloader
CELERYD_CONCURRENCY worker_concurrency
CELERYD_CONSUMER worker_consumer
CELERY_DISABLE_RATE_LIMITS worker_disable_rate_limits
CELERY_ENABLE_REMOTE_CONTROL worker_enable_remote_control
CELERYD_FORCE_EXECV worker_force_execv
CELERYD_HIJACK_ROOT_LOGGER worker_hijack_root_logger
CELERYD_LOG_COLOR worker_log_color
CELERYD_LOG_FORMAT worker_log_format
CELERYD_MAX_TASKS_PER_CHILD worker_max_tasks_per_child
CELERYD_POOL worker_pool
CELERYD_POOL_PUTLOCKS worker_pool_putlocks
CELERYD_POOL_RESTARTS worker_pool_restarts
CELERYD_PREFETCH_MULTIPLIER worker_prefetch_multiplier
CELERYD_REDIRECT_STDOUTS worker_redirect_stdouts
CELERYD_REDIRECT_STDOUTS_LEVEL worker_redirect_stdouts_level
CELERYD_SEND_EVENTS worker_send_task_events
CELERYD_STATE_DB worker_state_db
CELERYD_TASK_LOG_FORMAT worker_task_log_format
CELERYD_TIMER worker_timer
CELERYD_TIMER_PRECISION worker_timer_precision

Configuration Directives

General settings


A whitelist of content-types/serializers to allow.

If a message is received that is not in this list then the message will be discarded with an error.

By default any content type is enabled (including pickle and yaml) so make sure untrusted parties do not have access to your broker. See Security for more.


# using serializer name
accept_content = ['json']

# or the actual content-type (MIME)
accept_content = ['application/json']

Time and date settings


New in version 2.5.

If enabled dates and times in messages will be converted to use the UTC timezone.

Note that workers running Celery versions below 2.5 will assume a local timezone for all messages, so only enable if all workers have been upgraded.

Enabled by default since version 3.0.


Configure Celery to use a custom time zone. The timezone value can be any time zone supported by the pytz library.

If not set the UTC timezone is used. For backwards compatibility there is also a enable_utc setting, and this is set to false the system local timezone is used instead.

Task settings


This setting can be used to rewrite any task attribute from the configuration. The setting can be a dict, or a list of annotation objects that filter for tasks and return a map of attributes to change.

This will change the rate_limit attribute for the tasks.add task:

task_annotations = {'tasks.add': {'rate_limit': '10/s'}}

or change the same for all tasks:

task_annotations = {'*': {'rate_limit': '10/s'}}

You can change methods too, for example the on_failure handler:

def my_on_failure(self, exc, task_id, args, kwargs, einfo):
    print('Oh no! Task failed: {0!r}'.format(exc))

task_annotations = {'*': {'on_failure': my_on_failure}}

If you need more flexibility then you can use objects instead of a dict to choose which tasks to annotate:

class MyAnnotate(object):

    def annotate(self, task):
            return {'rate_limit': '10/s'}

task_annotations = (MyAnnotate(), {…})


Default compression used for task messages. Can be gzip, bzip2 (if available), or any custom compression schemes registered in the Kombu compression registry.

The default is to send uncompressed messages.


Default task message protocol version. Supports protocols: 1 and 2 (default is 1 for backwards compatibility).


A string identifying the default serialization method to use. Can be pickle (default), json, yaml, msgpack or any custom serialization methods that have been registered with kombu.serialization.registry.

See also



New in version 2.2.

Decides if publishing task messages will be retried in the case of connection loss or other connection errors. See also task_publish_retry_policy.

Enabled by default.


New in version 2.2.

Defines the default policy when retrying publishing a task message in the case of connection loss or other connection errors.

See Message Sending Retry for more information. .. _conf-task-execution:

Task execution settings


If this is True, all tasks will be executed locally by blocking until the task returns. apply_async() and Task.delay() will return an EagerResult instance, which emulates the API and behavior of AsyncResult, except the result is already evaluated.

That is, tasks will be executed locally instead of being sent to the queue.


If this is True, eagerly executed tasks (applied by task.apply(), or when the task_always_eager setting is enabled), will propagate exceptions.

It’s the same as always running apply() with throw=True.


Whether to store the task return values or not (tombstones). If you still want to store errors, just not successful return values, you can set task_store_errors_even_if_ignored.


If set, the worker stores all task errors in the result store even if Task.ignore_result is on.


If True the task will report its status as “started” when the task is executed by a worker. The default value is False as the normal behaviour is to not report that level of granularity. Tasks are either pending, finished, or waiting to be retried. Having a “started” state can be useful for when there are long running tasks and there is a need to report which task is currently running.


Task hard time limit in seconds. The worker processing the task will be killed and replaced with a new one when this is exceeded.


Task soft time limit in seconds.

The SoftTimeLimitExceeded exception will be raised when this is exceeded. The task can catch this to e.g. clean up before the hard time limit comes.


from celery.exceptions import SoftTimeLimitExceeded

def mytask():
        return do_work()
    except SoftTimeLimitExceeded:


Late ack means the task messages will be acknowledged after the task has been executed, not just before, which is the default behavior.


Even if task_acks_late is enabled, the worker will acknowledge tasks when the worker process executing them abrubtly exits or is signalled (e.g. KILL/INT, etc).

Setting this to true allows the message to be requeued instead, so that the task will execute again by the same worker, or another worker.


Enabling this can cause message loops; make sure you know what you’re doing.


The global default rate limit for tasks.

This value is used for tasks that does not have a custom rate limit The default is no rate limit.

See also

The setting:worker_disable_rate_limits setting can disable all rate limits.

Task result backend settings


The backend used to store task results (tombstones). Disabled by default. Can be one of the following:


Result serialization format. Default is pickle. See Serializers for information about supported serialization formats.


Optional compression method used for task results. Supports the same options as the task_serializer setting.

Default is no compression.


Time (in seconds, or a timedelta object) for when after stored task tombstones will be deleted.

A built-in periodic task will delete the results after this time (celery.backend_cleanup), assuming that celery beat is enabled. The task runs daily at 4am.

A value of None or 0 means results will never expire (depending on backend specifications).

Default is to expire after 1 day.


For the moment this only works with the amqp, database, cache, redis and MongoDB backends.

When using the database or MongoDB backends, celery beat must be running for the results to be expired.


Result backends caches ready results used by the client.

This is the total number of results to cache before older results are evicted. The default is 5000. 0 or None means no limit, and a value of -1 will disable the cache.

Database backend settings

Database URL Examples

To use the database backend you have to configure the result_backend setting with a connection URL and the db+ prefix:

result_backend = 'db+scheme://user:password@host:port/dbname'


# sqlite (filename)
result_backend = 'db+sqlite:///results.sqlite'

# mysql
result_backend = 'db+mysql://scott:tiger@localhost/foo'

# postgresql
result_backend = 'db+postgresql://scott:tiger@localhost/mydatabase'

# oracle
result_backend = 'db+oracle://scott:tiger@'

Please see Supported Databases for a table of supported databases, and Connection String for more information about connection strings (which is the part of the URI that comes after the db+ prefix).


This setting is no longer used as it’s now possible to specify the database URL directly in the result_backend setting.


To specify additional SQLAlchemy database engine options you can use the sqlalchmey_engine_options setting:

# echo enables verbose logging from SQLAlchemy.
sqlalchemy_engine_options = {'echo': True}


sqlalchemy_short_lived_sessions = True

Short lived sessions are disabled by default. If enabled they can drastically reduce performance, especially on systems processing lots of tasks. This option is useful on low-traffic workers that experience errors as a result of cached database connections going stale through inactivity. For example, intermittent errors like (OperationalError) (2006, ‘MySQL server has gone away’) can be fixed by enabling short lived sessions. This option only affects the database backend.


When SQLAlchemy is configured as the result backend, Celery automatically creates two tables to store result metadata for tasks. This setting allows you to customize the table names:

# use custom table names for the database result backend.
sqlalchemy_table_names = {
    'task': 'myapp_taskmeta',
    'group': 'myapp_groupmeta',

RPC backend settings


If set to True, result messages will be persistent. This means the messages will not be lost after a broker restart. The default is for the results to be transient.

Example configuration

result_backend = 'rpc://'
result_persistent = False

Cache backend settings


The cache backend supports the pylibmc and python-memcached libraries. The latter is used only if pylibmc is not installed.

Using a single memcached server:

result_backend = 'cache+memcached://'

Using multiple memcached servers:

result_backend = """

The “memory” backend stores the cache in memory only:

result_backend = 'cache'
cache_backend = 'memory'


You can set pylibmc options using the cache_backend_options setting:

cache_backend_options = {
    'binary': True,
    'behaviors': {'tcp_nodelay': True},


This setting is no longer used as it’s now possible to specify the cache backend directly in the result_backend setting.

Redis backend settings

Configuring the backend URL


The Redis backend requires the redis library:

To install the redis package use pip or easy_install:

$ pip install redis

This backend requires the result_backend setting to be set to a Redis URL:

result_backend = 'redis://:password@host:port/db'

For example:

result_backend = 'redis://localhost/0'

which is the same as:

result_backend = 'redis://'

The fields of the URL are defined as follows:

  • host

Host name or IP address of the Redis server. e.g. localhost.

  • port

Port to the Redis server. Default is 6379.

  • db

Database number to use. Default is 0. The db can include an optional leading slash.

  • password

Password used to connect to the database.


Maximum number of connections available in the Redis connection pool used for sending and retrieving results.


Socket timeout for connections to Redis from the result backend in seconds (int/float)

Default is 5 seconds.

MongoDB backend settings


The MongoDB backend requires the pymongo library:


This is a dict supporting the following keys:

  • database

    The database name to connect to. Defaults to celery.

  • taskmeta_collection

    The collection name to store task meta data. Defaults to celery_taskmeta.

  • max_pool_size

    Passed as max_pool_size to PyMongo’s Connection or MongoClient constructor. It is the maximum number of TCP connections to keep open to MongoDB at a given time. If there are more open connections than max_pool_size, sockets will be closed when they are released. Defaults to 10.

  • options

    Additional keyword arguments to pass to the mongodb connection constructor. See the pymongo docs to see a list of arguments supported.

Example configuration

result_backend = 'mongodb://'
mongodb_backend_settings = {
    'database': 'mydb',
    'taskmeta_collection': 'my_taskmeta_collection',

cassandra backend settings


This Cassandra backend driver requires cassandra-driver.

To install, use pip or easy_install:

$ pip install cassandra-driver

This backend requires the following configuration directives to be set.


List of host Cassandra servers. e.g.:

cassandra_servers = ['localhost']


Port to contact the Cassandra servers on. Default is 9042.


The keyspace in which to store the results. e.g.:

cassandra_keyspace = 'tasks_keyspace'


The table (column family) in which to store the results. e.g.:

cassandra_table = 'tasks'


The read consistency used. Values can be ONE, TWO, THREE, QUORUM, ALL, LOCAL_QUORUM, EACH_QUORUM, LOCAL_ONE.


The write consistency used. Values can be ONE, TWO, THREE, QUORUM, ALL, LOCAL_QUORUM, EACH_QUORUM, LOCAL_ONE.


Time-to-live for status entries. They will expire and be removed after that many seconds after adding. Default (None) means they will never expire.

Example configuration

cassandra_servers = ['localhost']
cassandra_keyspace = 'celery'
cassandra_table = 'tasks'
cassandra_read_consistency = 'ONE'
cassandra_write_consistency = 'ONE'
cassandra_entry_ttl = 86400

Riak backend settings


The Riak backend requires the riak library:

To install the riak package use pip or easy_install:

$ pip install riak

This backend requires the result_backend setting to be set to a Riak URL:

result_backend = "riak://host:port/bucket"

For example:

result_backend = "riak://localhost/celery

which is the same as:

result_backend = "riak://"

The fields of the URL are defined as follows:

  • host

Host name or IP address of the Riak server. e.g. “localhost”.

  • port

Port to the Riak server using the protobuf protocol. Default is 8087.

  • bucket

Bucket name to use. Default is celery. The bucket needs to be a string with ascii characters only.

Altenatively, this backend can be configured with the following configuration directives.


This is a dict supporting the following keys:

  • host

    The host name of the Riak server. Defaults to “localhost”.

  • port

    The port the Riak server is listening to. Defaults to 8087.

  • bucket

    The bucket name to connect to. Defaults to “celery”.

  • protocol

    The protocol to use to connect to the Riak server. This is not configurable via result_backend

IronCache backend settings


The IronCache backend requires the iron_celery library:

To install the iron_celery package use pip or easy_install:

$ pip install iron_celery

IronCache is configured via the URL provided in result_backend, for example:

result_backend = 'ironcache://project_id:token@'

Or to change the cache name:


For more information, see:

Couchbase backend settings


The Couchbase backend requires the couchbase library:

To install the couchbase package use pip or easy_install:

$ pip install couchbase

This backend can be configured via the result_backend set to a couchbase URL:

result_backend = 'couchbase://username:password@host:port/bucket'


This is a dict supporting the following keys:

  • host

    Host name of the Couchbase server. Defaults to localhost.

  • port

    The port the Couchbase server is listening to. Defaults to 8091.

  • bucket

    The default bucket the Couchbase server is writing to. Defaults to default.

  • username

    User name to authenticate to the Couchbase server as (optional).

  • password

    Password to authenticate to the Couchbase server (optional).

CouchDB backend settings


The CouchDB backend requires the pycouchdb library:

To install the couchbase package use pip or easy_install:

$ pip install pycouchdb

This backend can be configured via the result_backend set to a couchdb URL:

result_backend = 'couchdb://username:password@host:port/container'

The URL is formed out of the following parts:

  • username

    User name to authenticate to the CouchDB server as (optional).

  • password

    Password to authenticate to the CouchDB server (optional).

  • host

    Host name of the CouchDB server. Defaults to localhost.

  • port

    The port the CouchDB server is listening to. Defaults to 8091.

  • container

    The default container the CouchDB server is writing to. Defaults to default.

AMQP backend settings

Do not use in production.

This is the old AMQP result backend that creates one queue per task, if you want to send results back as message please consider using the RPC backend instead, or if you need the results to be persistent use a result backend designed for that purpose (e.g. Redis, or a database).


The AMQP backend requires RabbitMQ 1.1.0 or higher to automatically expire results. If you are running an older version of RabbitMQ you should disable result expiration like this:

result_expires = None


Name of the exchange to publish results in. Default is celeryresults.


The exchange type of the result exchange. Default is to use a direct exchange.


If set to True, result messages will be persistent. This means the messages will not be lost after a broker restart. The default is for the results to be transient.

Example configuration

result_backend = 'amqp'
result_expires = 18000  # 5 hours.

Filesystem backend settings

This backend can be configured using a file URL, for example:

CELERY_RESULT_BACKEND = 'file:///var/celery/results'

The configured directory needs to be shared and writeable by all servers using the backend.

If you are trying Celery on a single system you can simply use the backend without any further configuration. For larger clusters you could use NFS, GlusterFS, CIFS, HDFS (using FUSE) or any other filesystem.

Message Routing


Most users will not want to specify this setting and should rather use the automatic routing facilities.

If you really want to configure advanced routing, this setting should be a list of kombu.Queue objects the worker will consume from.

Note that workers can be overriden this setting via the -Q option, or individual queues from this list (by name) can be excluded using the -X option.

Also see Basics for more information.

The default is a queue/exchange/binding key of celery, with exchange type direct.

See also task_routes


A list of routers, or a single router used to route tasks to queues. When deciding the final destination of a task the routers are consulted in order.

A router can be specified as either:

  • A router class instances
  • A string which provides the path to a router class
  • A dict containing router specification. It will be converted to a celery.routes.MapRoute instance.


task_routes = {
    "": "default",
    "mytasks.add": "cpu-bound",
    "video.encode": {
        "queue": "video",
        "exchange": "media"
        "routing_key": "",

task_routes = ("myapp.tasks.Router", {"": "default})

Where myapp.tasks.Router could be:

class Router(object):

    def route_for_task(self, task, args=None, kwargs=None):
        if task == "":
            return "default"

route_for_task may return a string or a dict. A string then means it’s a queue name in task_queues, a dict means it’s a custom route.

When sending tasks, the routers are consulted in order. The first router that doesn’t return None is the route to use. The message options is then merged with the found route settings, where the routers settings have priority.

Example if apply_async() has these arguments:

Task.apply_async(immediate=False, exchange="video",

and a router returns:

{"immediate": True, "exchange": "urgent"}

the final message options will be:

immediate=True, exchange="urgent", routing_key="video.compress"

(and any default message options defined in the Task class)

Values defined in task_routes have precedence over values defined in task_queues when merging the two.

With the follow settings:

task_queues = {
    "cpubound": {
        "exchange": "cpubound",
        "routing_key": "cpubound",

task_routes = {
    "tasks.add": {
        "queue": "cpubound",
        "routing_key": "tasks.add",
        "serializer": "json",

The final routing options for tasks.add will become:

{"exchange": "cpubound",
 "routing_key": "tasks.add",
 "serializer": "json"}

See Routers for more examples.



This will set the default HA policy for a queue, and the value can either be a string (usually all):

task_queue_ha_policy = 'all'

Using ‘all’ will replicate the queue to all current nodes, Or you can give it a list of nodes to replicate to:

task_queue_ha_policy = ['rabbit@host1', 'rabbit@host2']

Using a list will implicitly set x-ha-policy to ‘nodes’ and x-ha-policy-params to the given list of nodes.

See for more information.


This option enables so that every worker has a dedicated queue, so that tasks can be routed to specific workers.

The queue name for each worker is automatically generated based on the worker hostname and a .dq suffix, using the C.dq exchange.

For example the queue name for the worker with node name becomes:

Then you can route the task to the task by specifying the hostname as the routing key and the C.dq exchange:

task_routes = {
    'tasks.add': {'exchange': 'C.dq', 'routing_key': ''}


If enabled (default), any queues specified that are not defined in task_queues will be automatically created. See Automatic routing.


The name of the default queue used by .apply_async if the message has no route or no custom queue has been specified.

This queue must be listed in task_queues. If task_queues is not specified then it is automatically created containing one queue entry, where this name is used as the name of that queue.

The default is: celery.


Name of the default exchange to use when no custom exchange is specified for a key in the task_queues setting.

The default is: celery.


Default exchange type used when no custom exchange type is specified for a key in the task_queues setting. The default is: direct.


The default routing key used when no custom routing key is specified for a key in the task_queues setting.

The default is: celery.


Can be transient or persistent. The default is to send persistent messages.

Broker Settings


Default broker URL. This must be an URL in the form of:


Only the scheme part (transport://) is required, the rest is optional, and defaults to the specific transports default values.

The transport part is the broker implementation to use, and the default is amqp, which uses librabbitmq by default or falls back to pyamqp if that is not installed. Also there are many other choices including redis, beanstalk, sqlalchemy, django, mongodb, couchdb. It can also be a fully qualified path to your own transport implementation.

More than broker URL, of the same transport, can also be specified. The broker URLs can be passed in as a single string that is semicolon delimited:

broker_url = 'transport://userid:password@hostname:port//;transport://userid:password@hostname:port//'

Or as a list:

broker_url = [

The brokers will then be used in the broker_failover_strategy.

See URLs in the Kombu documentation for more information.


Default failover strategy for the broker Connection object. If supplied, may map to a key in ‘kombu.connection.failover_strategies’, or be a reference to any method that yields a single item from a supplied list.


# Random failover strategy
def random_failover_strategy(servers):
    it = list(it)  # don't modify callers list
    shuffle = random.shuffle
    for _ in repeat(None):
        yield it[0]

broker_failover_strategy = random_failover_strategy


transports supported:

It’s not always possible to detect connection loss in a timely manner using TCP/IP alone, so AMQP defines something called heartbeats that’s is used both by the client and the broker to detect if a connection was closed.

Heartbeats are disabled by default.

If the heartbeat value is 10 seconds, then the heartbeat will be monitored at the interval specified by the broker_heartbeat_checkrate setting, which by default is double the rate of the heartbeat value (so for the default 10 seconds, the heartbeat is checked every 5 seconds).


transports supported:

At intervals the worker will monitor that the broker has not missed too many heartbeats. The rate at which this is checked is calculated by dividing the broker_heartbeat value with this value, so if the heartbeat is 10.0 and the rate is the default 2.0, the check will be performed every 5 seconds (twice the heartbeat sending rate).


transports supported:
 pyamqp, redis

Toggles SSL usage on broker connection and SSL settings.

If True the connection will use SSL with default SSL settings. If set to a dict, will configure SSL connection according to the specified policy. The format used is python ssl.wrap_socket() options.

Default is False (no SSL).

Note that SSL socket is generally served on a separate port by the broker.

Example providing a client cert and validating the server cert against a custom certificate authority:

import ssl

broker_use_ssl = {
  'keyfile': '/var/ssl/private/worker-key.pem',
  'certfile': '/var/ssl/amqp-server-cert.pem',
  'ca_certs': '/var/ssl/myca.pem',
  'cert_reqs': ssl.CERT_REQUIRED


Be careful using broker_use_ssl=True, it is possible that your default configuration do not validate the server cert at all, please read Python ssl module security considerations.


New in version 2.3.

The maximum number of connections that can be open in the connection pool.

The pool is enabled by default since version 2.5, with a default limit of ten connections. This number can be tweaked depending on the number of threads/greenthreads (eventlet/gevent) using a connection. For example running eventlet with 1000 greenlets that use a connection to the broker, contention can arise and you should consider increasing the limit.

If set to None or 0 the connection pool will be disabled and connections will be established and closed for every use.

Default (since 2.5) is to use a pool of 10 connections.


The default timeout in seconds before we give up establishing a connection to the AMQP server. Default is 4 seconds.


Automatically try to re-establish the connection to the AMQP broker if lost.

The time between retries is increased for each retry, and is not exhausted before broker_connection_max_retries is exceeded.

This behavior is on by default.


Maximum number of retries before we give up re-establishing a connection to the AMQP broker.

If this is set to 0 or None, we will retry forever.

Default is 100 retries.


Set custom amqp login method, default is AMQPLAIN.


New in version 2.2.

A dict of additional options passed to the underlying transport.

See your transport user manual for supported options (if any).

Example setting the visibility timeout (supported by Redis and SQS transports):

broker_transport_options = {'visibility_timeout': 18000}  # 5 hours



A sequence of modules to import when the worker starts.

This is used to specify the task modules to import, but also to import signal handlers and additional remote control commands, etc.

The modules will be imported in the original order.


Exact same semantics as imports, but can be used as a means to have different import categories.

The modules in this setting are imported after the modules in imports.


The number of concurrent worker processes/threads/green threads executing tasks.

If you’re doing mostly I/O you can have more processes, but if mostly CPU-bound, try to keep it close to the number of CPUs on your machine. If not set, the number of CPUs/cores on the host will be used.

Defaults to the number of available CPUs.


How many messages to prefetch at a time multiplied by the number of concurrent processes. The default is 4 (four messages for each process). The default setting is usually a good choice, however – if you have very long running tasks waiting in the queue and you have to start the workers, note that the first worker to start will receive four times the number of messages initially. Thus the tasks may not be fairly distributed to the workers.

To disable prefetching, set worker_prefetch_multiplier to 1. Changing that setting to 0 will allow the worker to keep consuming as many messages as it wants.

For more on prefetching, read Prefetch Limits


Tasks with ETA/countdown are not affected by prefetch limits.


In some cases a worker may be killed without proper cleanup, and the worker may have published a result before terminating. This value specifies how long we wait for any missing results before raising a WorkerLostError exception.

Default is 10.0


Maximum number of tasks a pool worker process can execute before it’s replaced with a new one. Default is no limit.


Maximum amount of resident memory that may be consumed by a worker before it will be replaced by a new worker. If a single task causes a worker to exceed this limit, the task will be completed, and the worker will be replaced afterwards. Default: no limit.


Disable all rate limits, even if tasks has explicit rate limits set.


Name of the file used to stores persistent worker state (like revoked tasks). Can be a relative or absolute path, but be aware that the suffix .db may be appended to the file name (depending on Python version).

Can also be set via the --statedb argument to worker.

Not enabled by default.


Set the maximum time in seconds that the ETA scheduler can sleep between rechecking the schedule. Default is 1 second.

Setting this value to 1 second means the schedulers precision will be 1 second. If you need near millisecond precision you can set this to 0.1.


Specify if remote control of the workers is enabled.

Default is True.

Error E-Mails


The default value for the Task.send_error_emails attribute, which if set to True means errors occurring during task execution will be sent to admins by email.

Disabled by default.


List of (name, email_address) tuples for the administrators that should receive error emails.


The email address this worker sends emails from. Default is celery@localhost.


The mail server to use. Default is localhost.


User name (if required) to log on to the mail server with.


Password (if required) to log on to the mail server with.


The port the mail server is listening on. Default is 25.


Use SSL when connecting to the SMTP server. Disabled by default.


Use TLS when connecting to the SMTP server. Disabled by default.


Timeout in seconds for when we give up trying to connect to the SMTP server when sending emails.

The default is 2 seconds.


New in version 4.0.

Charset for outgoing emails. Default is “us-ascii”.

Example E-Mail configuration

This configuration enables the sending of error emails to and

# Enables error emails.
task_send_error_emails = True

# Name and email addresses of recipients
admins = (
    ('George Costanza', ''),
    ('Cosmo Kramer', ''),

# Email address used as sender (From field).
server_email = ''

# Mailserver configuration
email_host = ''
email_port = 25
# email_host_user = 'servers'
# email_host_password = 's3cr3t'



Send task-related events so that tasks can be monitored using tools like flower. Sets the default value for the workers -E argument.


New in version 2.2.

If enabled, a task-sent event will be sent for every task so tasks can be tracked before they are consumed by a worker.

Disabled by default.


transports supported:

Message expiry time in seconds (int/float) for when messages sent to a monitor clients event queue is deleted (x-message-ttl)

For example, if this value is set to 10 then a message delivered to this queue will be deleted after 10 seconds.

Disabled by default.


transports supported:

Expiry time in seconds (int/float) for when after a monitor clients event queue will be deleted (x-expires).

Default is never, relying on the queue autodelete setting.


Message serialization format used when sending event messages. Default is json. See Serializers.



New in version 2.2.

By default any previously configured handlers on the root logger will be removed. If you want to customize your own logging handlers, then you can disable this behavior by setting worker_hijack_root_logger = False.


Logging can also be customized by connecting to the celery.signals.setup_logging signal.


Enables/disables colors in logging output by the Celery apps.

By default colors are enabled if

  1. the app is logging to a real terminal, and not a file.
  2. the app is not running on Windows.


The format to use for log messages.

Default is [%(asctime)s: %(levelname)s/%(processName)s] %(message)s

See the Python logging module for more information about log formats.


The format to use for log messages logged in tasks. Can be overridden using the --loglevel option to worker.

Default is:

[%(asctime)s: %(levelname)s/%(processName)s]
    [%(task_name)s(%(task_id)s)] %(message)s

See the Python logging module for more information about log formats.


If enabled stdout and stderr will be redirected to the current logger.

Enabled by default. Used by celery worker and celery beat.


The log level output to stdout and stderr is logged as. Can be one of DEBUG, INFO, WARNING, ERROR or CRITICAL.

Default is WARNING.



New in version 2.5.

The relative or absolute path to a file containing the private key used to sign messages when Message Signing is used.


New in version 2.5.

The relative or absolute path to an X.509 certificate file used to sign messages when Message Signing is used.


New in version 2.5.

The directory containing X.509 certificates used for Message Signing. Can be a glob with wildcards, (for example /etc/certs/*.pem).

Custom Component Classes (advanced)


Name of the pool class used by the worker.


Never use this option to select the eventlet or gevent pool. You must use the -P option instead, otherwise the monkey patching will happen too late and things will break in strange and silent ways.

Default is celery.concurrency.prefork:TaskPool.


If enabled the worker pool can be restarted using the pool_restart remote control command.

Disabled by default.


New in version 2.2.

Name of the autoscaler class to use.

Default is celery.worker.autoscale:Autoscaler.


Name of the autoreloader class used by the worker to reload Python modules and files that have changed.

Default is: celery.worker.autoreload:Autoreloader.


Name of the consumer class used by the worker. Default is celery.worker.consumer.Consumer


Name of the ETA scheduler class used by the worker. Default is kombu.async.hub.timer.Timer, or one overrided by the pool implementation.

Beat Settings (celery beat)


The periodic task schedule used by beat. See Entries.


The default scheduler class. Default is celery.beat:PersistentScheduler.

Can also be set via the -S argument to beat.


Name of the file used by PersistentScheduler to store the last run times of periodic tasks. Can be a relative or absolute path, but be aware that the suffix .db may be appended to the file name (depending on Python version).

Can also be set via the --schedule argument to beat.


The number of periodic tasks that can be called before another database sync is issued. Defaults to 0 (sync based on timing - default of 3 minutes as determined by scheduler.sync_every). If set to 1, beat will call sync after every task message sent.


The maximum number of seconds beat can sleep between checking the schedule.

The default for this value is scheduler specific. For the default celery beat scheduler the value is 300 (5 minutes), but for e.g. the django-celery database scheduler it is 5 seconds because the schedule may be changed externally, and so it must take changes to the schedule into account.

Also when running celery beat embedded (-B) on Jython as a thread the max interval is overridden and set to 1 so that it’s possible to shut down in a timely manner.