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

-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

Copyright © 2017-2026 Asif Saif Uddin, core team & contributors. All rights reserved.
Celery is licensed under The BSD License (3 Clause, also known as the new BSD license). The license is an OSI approved Open Source license and is GPL-compatible.
https://docs.celeryq.dev/en/stable/reference/cli.html