This document describes the current stable version of Celery (5.3). For development docs, go here.

Command Line Interface

Note

The prefix CELERY_ must be added to the names of the environment variables described below. E.g., APP becomes CELERY_APP.

celery

Celery command entrypoint.

celery [OPTIONS] COMMAND [ARGS]...

Options

-A, --app <app>
-b, --broker <broker>
--result-backend <result_backend>
--loader <loader>
--config <config>
--workdir <workdir>
-C, --no-color
-q, --quiet
--version
--skip-checks

Skip Django core checks on startup. Setting the SKIP_CHECKS environment variable to any non-empty string will have the same effect.

Environment variables

APP

Provide a default for -A

BROKER_URL

Provide a default for -b

RESULT_BACKEND

Provide a default for --result-backend

LOADER

Provide a default for --loader

CONFIG_MODULE

Provide a default for --config

NO_COLOR

Provide a default for -C

SKIP_CHECKS

Provide a default for --skip-checks

amqp

AMQP Administration Shell.

Also works for non-AMQP transports (but not ones that store declarations in memory).

celery amqp [OPTIONS] COMMAND [ARGS]...

basic.ack

celery amqp basic.ack [OPTIONS] DELIVERY_TAG

Arguments

DELIVERY_TAG

Required argument

basic.get

celery amqp basic.get [OPTIONS] QUEUE [NO_ACK]

Arguments

QUEUE

Required argument

NO_ACK

Optional argument

basic.publish

celery amqp basic.publish [OPTIONS] MSG EXCHANGE ROUTING_KEY [MANDATORY]
                          [IMMEDIATE]

Arguments

MSG

Required argument

EXCHANGE

Required argument

ROUTING_KEY

Required argument

MANDATORY

Optional argument

IMMEDIATE

Optional argument

exchange.declare

celery amqp exchange.declare [OPTIONS] EXCHANGE TYPE [PASSIVE] [DURABLE]
                             [AUTO_DELETE]

Arguments

EXCHANGE

Required argument

TYPE

Required argument

PASSIVE

Optional argument

DURABLE

Optional argument

AUTO_DELETE

Optional argument

exchange.delete

celery amqp exchange.delete [OPTIONS] EXCHANGE IF_UNUSED

Arguments

EXCHANGE

Required argument

IF_UNUSED

Required argument

queue.bind

celery amqp queue.bind [OPTIONS] QUEUE EXCHANGE ROUTING_KEY

Arguments

QUEUE

Required argument

EXCHANGE

Required argument

ROUTING_KEY

Required argument

queue.declare

celery amqp queue.declare [OPTIONS] QUEUE [PASSIVE] [DURABLE] [AUTO_DELETE]

Arguments

QUEUE

Required argument

PASSIVE

Optional argument

DURABLE

Optional argument

AUTO_DELETE

Optional argument

queue.delete

celery amqp queue.delete [OPTIONS] QUEUE [IF_UNUSED] [IF_EMPTY]

Arguments

QUEUE

Required argument

IF_UNUSED

Optional argument

IF_EMPTY

Optional argument

queue.purge

celery amqp queue.purge [OPTIONS] QUEUE

Arguments

QUEUE

Required argument

repl

Start an interactive shell. All subcommands are available in it.

param old_ctx:

The current Click context.

param prompt_kwargs:

Parameters passed to prompt_toolkit.PromptSession().

If stdin is not a TTY, no prompt will be printed, but only commands read from stdin.

celery amqp repl [OPTIONS]

beat

Start the beat periodic task scheduler.

celery beat [OPTIONS]

Options

--detach

Detach and run in the background as a daemon.

-s, --schedule <schedule>

Path to the schedule database. Defaults to celerybeat-schedule.The extension ‘.db’ may be appended to the filename.

-S, --scheduler <scheduler>

Scheduler class to use.

--max-interval <max_interval>

Max seconds to sleep between schedule iterations.

-l, --loglevel <loglevel>

Logging level.

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL | FATAL

-f, --logfile <logfile>

Log destination; defaults to stderr

--pidfile <pidfile>
--uid <uid>
--gid <gid>
--umask <umask>
--executable <executable>

call

Call a task by name.

celery call [OPTIONS] NAME

Options

-a, --args <args>

Positional arguments.

-k, --kwargs <kwargs>

Keyword arguments.

--eta <eta>

scheduled time.

--countdown <countdown>

eta in seconds from now.

--expires <expires>

expiry time.

--serializer <serializer>

task serializer.

--queue <queue>

custom queue name.

--exchange <exchange>

custom exchange name.

--routing-key <routing_key>

custom routing key.

Arguments

NAME

Required argument

control

Workers remote control.

Availability: RabbitMQ (AMQP), Redis, and MongoDB transports.

celery control [OPTIONS] {revoke|revoke_by_stamped_headers|terminate|rate_limi
               t|time_limit|election|enable_events|disable_events|heartbeat|po
               ol_grow|pool_shrink|pool_restart|autoscale|shutdown|add_consume
               r|cancel_consumer}

Options

-t, --timeout <timeout>

Timeout in seconds waiting for reply.

-d, --destination <destination>

Comma separated list of destination node names.

-j, --json

Use json as output format.

Arguments

ACTION

Required argument

events

Event-stream utilities.

celery events [OPTIONS]

Options

-d, --dump
-c, --camera <camera>
-d, --detach
-F, --frequency, --freq <frequency>
-r, --maxrate <maxrate>
-l, --loglevel <loglevel>

Logging level.

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL | FATAL

-f, --logfile <logfile>

Log destination; defaults to stderr

--pidfile <pidfile>
--uid <uid>
--gid <gid>
--umask <umask>
--executable <executable>

graph

The celery graph command.

celery graph [OPTIONS] COMMAND [ARGS]...

bootsteps

Display bootsteps graph.

celery graph bootsteps [OPTIONS]

workers

Display workers graph.

celery graph workers [OPTIONS]

inspect

Inspect the worker at runtime.

Availability: RabbitMQ (AMQP) and Redis transports.

celery inspect [OPTIONS] {report|conf|query_task|clock|ping|stats|scheduled|re
               served|active|revoked|registered|objgraph|memsample|memdump|act
               ive_queues}

Options

-t, --timeout <timeout>

Timeout in seconds waiting for reply.

-d, --destination <destination>

Comma separated list of destination node names.

-j, --json

Use json as output format.

Arguments

ACTION

Required argument

list

Get info from broker.

Note:

For RabbitMQ the management plugin is required.

celery list [OPTIONS] COMMAND [ARGS]...

bindings

Inspect queue bindings.

celery list bindings [OPTIONS]

logtool

The celery logtool command.

celery logtool [OPTIONS] COMMAND [ARGS]...

debug

celery logtool debug [OPTIONS] [FILES]...

Arguments

FILES

Optional argument(s)

errors

celery logtool errors [OPTIONS] [FILES]...

Arguments

FILES

Optional argument(s)

incomplete

celery logtool incomplete [OPTIONS] [FILES]...

Arguments

FILES

Optional argument(s)

stats

celery logtool stats [OPTIONS] [FILES]...

Arguments

FILES

Optional argument(s)

traces

celery logtool traces [OPTIONS] [FILES]...

Arguments

FILES

Optional argument(s)

migrate

Migrate tasks from one broker to another.

Warning:

This command is experimental, make sure you have a backup of the tasks before you continue.

celery migrate [OPTIONS] SOURCE DESTINATION

Options

-n, --limit <limit>

Number of tasks to consume.

-t, --timeout <timeout>

Timeout in seconds waiting for tasks.

-a, --ack-messages

Ack messages from source broker.

-T, --tasks <tasks>

List of task names to filter on.

-Q, --queues <queues>

List of queues to migrate.

-F, --forever

Continually migrate tasks until killed.

Arguments

SOURCE

Required argument

DESTINATION

Required argument

multi

Start multiple worker instances.

celery multi [OPTIONS]

purge

Erase all messages from all known task queues.

Warning:

There’s no undo operation for this command.

celery purge [OPTIONS]

Options

-f, --force

Don’t prompt for verification.

-Q, --queues <queues>

Comma separated list of queue names to purge.

-X, --exclude-queues <exclude_queues>

Comma separated list of queues names not to purge.

report

Shows information useful to include in bug-reports.

celery report [OPTIONS]

result

Print the return value for a given task id.

celery result [OPTIONS] TASK_ID

Options

-t, --task <task>

Name of task (if custom backend).

--traceback

Show traceback instead.

Arguments

TASK_ID

Required argument

shell

Start shell session with convenient access to celery symbols.

The following symbols will be added to the main globals: - celery: the current application. - chord, group, chain, chunks,

xmap, xstarmap subtask, Task

  • all registered tasks.

celery shell [OPTIONS]

Options

-I, --ipython

Force IPython.

-B, --bpython

Force bpython.

--python

Force default Python shell.

-T, --without-tasks

Don’t add tasks to locals.

--eventlet

Use eventlet.

--gevent

Use gevent.

status

Show list of workers that are online.

celery status [OPTIONS]

Options

-t, --timeout <timeout>

Timeout in seconds waiting for reply.

-d, --destination <destination>

Comma separated list of destination node names.

-j, --json

Use json as output format.

upgrade

Perform upgrade between versions.

celery upgrade [OPTIONS] COMMAND [ARGS]...

settings

Migrate settings from Celery 3.x to Celery 4.x.

celery upgrade settings [OPTIONS] FILENAME

Options

--django

Upgrade Django project.

--compat

Maintain backwards compatibility.

--no-backup

Don’t backup original files.

Arguments

FILENAME

Required argument

worker

Start worker instance.

Examples
——–
$ celery –app=proj worker -l INFO
$ celery -A proj worker -l INFO -Q hipri,lopri
$ celery -A proj worker –concurrency=4
$ celery -A proj worker –concurrency=1000 -P eventlet
$ celery worker –autoscale=10,0
celery worker [OPTIONS]

Options

-n, --hostname <hostname>

Set custom hostname (e.g., ‘w1@%%h’). Expands: %%h (hostname), %%n (name) and %%d, (domain).

-D, --detach

Start worker as a background process.

-S, --statedb <statedb>

Path to the state database. The extension ‘.db’ may be appended to the filename.

-l, --loglevel <loglevel>

Logging level.

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL | FATAL

-O, --optimization <optimization>

Apply optimization profile.

Options:

default | fair

--prefetch-multiplier <prefetch multiplier>

Set custom prefetch multiplier value for this worker instance.

-c, --concurrency <concurrency>

Number of child processes processing the queue. The default is the number of CPUs available on your system.

-P, --pool <pool>

Pool implementation.

Options:

prefork | eventlet | gevent | solo | processes | threads | custom

-E, --task-events, --events

Send task-related events that can be captured by monitors like celery events, celerymon, and others.

--time-limit <time_limit>

Enables a hard time limit (in seconds int/float) for tasks.

--soft-time-limit <soft_time_limit>

Enables a soft time limit (in seconds int/float) for tasks.

--max-tasks-per-child <max_tasks_per_child>

Maximum number of tasks a pool worker can execute before it’s terminated and replaced by a new worker.

--max-memory-per-child <max_memory_per_child>

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

--purge, --discard
-Q, --queues <queues>
-X, --exclude-queues <exclude_queues>
-I, --include <include>
--without-gossip
--without-mingle
--without-heartbeat
--heartbeat-interval <heartbeat_interval>
--autoscale <autoscale>
-B, --beat
-s, --schedule-filename, --schedule <schedule_filename>
--scheduler <scheduler>
-f, --logfile <logfile>

Log destination; defaults to stderr

--pidfile <pidfile>
--uid <uid>
--gid <gid>
--umask <umask>
--executable <executable>