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

  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.

    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.

    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.

    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.

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

#### bootsteps

Display bootsteps graph.

    celery graph bootsteps [OPTIONS]

#### workers

Display workers graph.

    celery graph workers [OPTIONS]

### inspect

Inspect the workers by sending them the COMMAND inspect command.

Availability: RabbitMQ (AMQP) and Redis transports.

    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.

    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.

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