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

Command Line Interface¶

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¶

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

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.shortcuts.prompt().

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

--pidfile <pidfile>¶

--uid <uid>¶

--uid <uid>¶

--gid <gid>¶

--umask <umask>¶

--executable <executable>¶

call¶

Call a task by name.

celery call [OPTIONS] NAME

Options

--routing-key <routing_key>¶: custom routing key.

--exchange <exchange>¶: custom exchange name.

--queue <queue>¶: custom queue name.

--serializer <serializer>¶: task serializer.

--expires <expires>¶: expiry time.

--countdown <countdown>¶: eta in seconds from now.

--eta <eta>¶: scheduled time.

-k, --kwargs <kwargs>¶: Keyword arguments.

-a, --args <args>¶: Positional arguments.

Arguments

NAME¶: Required argument

control¶

Workers remote control.

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

celery control [OPTIONS] [revoke|terminate|rate_limit|time_limit|election|enab
               le_events|disable_events|heartbeat|pool_grow|pool_shrink|pool_r
               estart|autoscale|shutdown|add_consumer|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>¶

--pidfile <pidfile>¶

--uid <uid>¶

--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 beappended to the filename.

-l, --loglevel <loglevel>¶

Logging level.

Options: DEBUG|INFO|WARNING|ERROR|CRITICAL|FATAL

-O <optimization>¶

Apply optimization profile.

Options: default|fair

--prefetch-multiplier <prefetch multiplier>¶: Set custom prefetch multiplier valuefor this worker instance.

-c, --concurrency <concurrency>¶: Number of child processes processing the queue. The default is the number of CPUs availableon your system.

-P, --pool <pool>¶

Pool implementation.

Options: prefork|eventlet|gevent|solo

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

--without-mingle <without_mingle>¶

--without-heartbeat <without_heartbeat>¶

--heartbeat-interval <heartbeat_interval>¶

--autoscale <autoscale>¶

-B, --beat¶

-s, --schedule-filename, --schedule <schedule_filename>¶

--scheduler <scheduler>¶

-f, --logfile <logfile>¶

--pidfile <pidfile>¶

--uid <uid>¶

--uid <uid>¶

--gid <gid>¶

--umask <umask>¶

--executable <executable>¶