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

Usage

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

Usage

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

basic.ack

Usage

celery amqp basic.ack [OPTIONS] DELIVERY_TAG

Arguments

DELIVERY_TAG

Required argument

basic.get

Usage

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

Arguments

QUEUE

Required argument

NO_ACK

Optional argument

basic.publish

Usage

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

Usage

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

Usage

celery amqp exchange.delete [OPTIONS] EXCHANGE IF_UNUSED

Arguments

EXCHANGE

Required argument

IF_UNUSED

Required argument

queue.bind

Usage

celery amqp queue.bind [OPTIONS] QUEUE EXCHANGE ROUTING_KEY

Arguments

QUEUE

Required argument

EXCHANGE

Required argument

ROUTING_KEY

Required argument

queue.declare

Usage

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

Usage

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

Arguments

QUEUE

Required argument

IF_UNUSED

Optional argument

IF_EMPTY

Optional argument

queue.purge

Usage

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.

Usage

celery amqp repl [OPTIONS]

beat

Start the beat periodic task scheduler.

Usage

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.

--enable-remote-control, --no-enable-remote-control

Answer celery inspect ping, so that beat can be health-checked. Overrides the beat_enable_remote_control setting.

-n, --hostname <hostname>

Node name to answer remote control commands on. Defaults to celerybeat@%h.

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

Usage

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

Send the COMMAND control command to the workers.

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

Usage

celery control [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.

Usage

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>

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.

Usage

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

bootsteps

Display bootsteps graph.

Usage

celery graph bootsteps [OPTIONS]

workers

Display workers graph.

Usage

celery graph workers [OPTIONS]

inspect

Inspect the workers by sending them the COMMAND inspect command.

Availability: RabbitMQ (AMQP) and Redis transports.

Usage

celery inspect [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.

Usage

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

bindings

Inspect queue bindings.

Usage

celery list bindings [OPTIONS]

logtool

The celery logtool command.

Usage

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

debug

Usage

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

Arguments

FILES

Optional argument(s)

errors

Usage

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

Arguments

FILES

Optional argument(s)

incomplete

Usage

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

Arguments

FILES

Optional argument(s)

stats

Usage

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

Arguments

FILES

Optional argument(s)

traces

Usage

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.

Usage

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.

Usage

celery multi [OPTIONS]

purge

Erase all messages from all known task queues.

Warning:

There’s no undo operation for this command.

Usage

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.

Usage

celery report [OPTIONS]

result

Print the return value for a given task id.

Usage

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.

Usage

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.

Usage

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.

Usage

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

settings

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

Usage

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

Usage

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.

--disable-prefetch

Disable broker prefetching. The worker will only fetch a task when a process slot is available. Only supported with Redis brokers.

-c, --concurrency <concurrency>

Number of child processes processing the queue. The default is the number of CPUs available on your system. Use ‘auto’ to size the prefork pool from the cgroup CPU quota and CPU affinity mask (Linux only). For the threads, gevent, eventlet and solo pools ‘auto’ is a no-op and uses the number of CPUs available to the process.

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

--pool-start-method <pool_start_method>

Start method used to create prefork pool child processes. ‘fork’ (default) is faster and shares memory copy-on-write but is unsafe with threads/C-extensions; ‘spawn’ starts each child in a fresh interpreter.

Options:

fork | spawn

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