This document describes the current stable version of Celery (5.5). 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).

celeryamqp[OPTIONS]COMMAND[ARGS]...

basic.ack 

celeryamqpbasic.ack[OPTIONS]DELIVERY_TAG

Arguments

DELIVERY_TAG

Required argument

basic.get 

celeryamqpbasic.get[OPTIONS]QUEUE[NO_ACK]

Arguments

QUEUE

Required argument

NO_ACK

Optional argument

basic.publish 

celeryamqpbasic.publish[OPTIONS]MSGEXCHANGEROUTING_KEY[MANDATORY]
[IMMEDIATE]

Arguments

MSG

Required argument

EXCHANGE

Required argument

ROUTING_KEY

Required argument

MANDATORY

Optional argument

IMMEDIATE

Optional argument

exchange.declare 

celeryamqpexchange.declare[OPTIONS]EXCHANGETYPE[PASSIVE][DURABLE]
[AUTO_DELETE]

Arguments

EXCHANGE

Required argument

TYPE

Required argument

PASSIVE

Optional argument

DURABLE

Optional argument

AUTO_DELETE

Optional argument

exchange.delete 

celeryamqpexchange.delete[OPTIONS]EXCHANGEIF_UNUSED

Arguments

EXCHANGE

Required argument

IF_UNUSED

Required argument

queue.bind 

celeryamqpqueue.bind[OPTIONS]QUEUEEXCHANGEROUTING_KEY

Arguments

QUEUE

Required argument

EXCHANGE

Required argument

ROUTING_KEY

Required argument

queue.declare 

celeryamqpqueue.declare[OPTIONS]QUEUE[PASSIVE][DURABLE][AUTO_DELETE]

Arguments

QUEUE

Required argument

PASSIVE

Optional argument

DURABLE

Optional argument

AUTO_DELETE

Optional argument

queue.delete 

celeryamqpqueue.delete[OPTIONS]QUEUE[IF_UNUSED][IF_EMPTY]

Arguments

QUEUE

Required argument

IF_UNUSED

Optional argument

IF_EMPTY

Optional argument

queue.purge 

celeryamqpqueue.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.

celeryamqprepl[OPTIONS]

beat

Start the beat periodic task scheduler.

celerybeat[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>

PID file path; defaults to no PID file

--uid <uid>

Drops privileges to this user ID

--gid <gid>

Drops privileges to this group ID

--umask <umask>

Create files and directories with this umask

--executable <executable>

Override path to the Python executable

call

Call a task by name.

celerycall[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

Send the COMMAND control command to the workers.

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

celerycontrol[OPTIONS]COMMAND

Options

--list

List available control commands and exit.

-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

COMMAND

Required argument

events

Event-stream utilities.

celeryevents[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>

PID file path; defaults to no PID file

--uid <uid>

Drops privileges to this user ID

--gid <gid>

Drops privileges to this group ID

--umask <umask>

Create files and directories with this umask

--executable <executable>

Override path to the Python executable

graph

The celery graph command.

celerygraph[OPTIONS]COMMAND[ARGS]...

bootsteps

Display bootsteps graph.

celerygraphbootsteps[OPTIONS]

workers

Display workers graph.

celerygraphworkers[OPTIONS]

inspect

Inspect the workers by sending them the COMMAND inspect command.

Availability: RabbitMQ (AMQP) and Redis transports.

celeryinspect[OPTIONS]COMMAND

Options

--list

List available inspect commands and exit.

-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

COMMAND

Required argument

list

Get info from broker.

Note:

For RabbitMQ the management plugin is required.

celerylist[OPTIONS]COMMAND[ARGS]...

bindings

Inspect queue bindings.

celerylistbindings[OPTIONS]

logtool

The celery logtool command.

celerylogtool[OPTIONS]COMMAND[ARGS]...

debug 

celerylogtooldebug[OPTIONS][FILES]...

Arguments

FILES

Optional argument(s)

errors 

celerylogtoolerrors[OPTIONS][FILES]...

Arguments

FILES

Optional argument(s)

incomplete 

celerylogtoolincomplete[OPTIONS][FILES]...

Arguments

FILES

Optional argument(s)

stats 

celerylogtoolstats[OPTIONS][FILES]...

Arguments

FILES

Optional argument(s)

traces 

celerylogtooltraces[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.

celerymigrate[OPTIONS]SOURCEDESTINATION

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.

celerymulti[OPTIONS]

purge

Erase all messages from all known task queues.

Warning:

There’s no undo operation for this command.

celerypurge[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.

celeryreport[OPTIONS]

result

Print the return value for a given task id.

celeryresult[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.

celeryshell[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.

celerystatus[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.

celeryupgrade[OPTIONS]COMMAND[ARGS]...

settings

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

celeryupgradesettings[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
celeryworker[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.

--disable-prefetch

Disable broker prefetching. The worker will only fetch a task when a process slot is available.

-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>

PID file path; defaults to no PID file

--uid <uid>

Drops privileges to this user ID

--gid <gid>

Drops privileges to this group ID

--umask <umask>

Create files and directories with this umask

--executable <executable>

Override path to the Python executable