# Django 5.2.9 documentation

# Tasks

New in Django 6.0.

The Task framework provides the contract and plumbing for background work, not the engine that runs it. The Tasks API defines how work is described, queued, and tracked, but leaves actual execution to external infrastructure.

## Task definition

### The `task` decorator

task(*, priority=0, queue_name='default', backend='default', takes_context=False)

  The `@task` decorator defines a `Task` instance. This has the following optional arguments:

  - `priority`: Sets the `priority` of the `Task`. Defaults to 0.

  - `queue_name`: Sets the `queue_name` of the `Task`. Defaults to `"default"`.

  - `backend`: Sets the `backend` of the `Task`. Defaults to `"default"`.

  - `takes_context`: Controls whether the `Task` function accepts a `TaskContext`. Defaults to `False`. See Task context for details.

  If the defined `Task` is not valid according to the backend, `InvalidTask` is raised.

  See defining tasks for usage examples.

### `Task`

class Task

  Represents a Task to be run in the background. Tasks should be defined using the `task()` decorator.

  Attributes of `Task` cannot be modified. See modifying Tasks for details.

  priority

    The priority of the `Task`. Priorities must be between -100 and 100, where larger numbers are higher priority, and will be run sooner.

    The backend must have `supports_priority` set to `True` to use this feature.

  backend

    The alias of the backend the `Task` should be enqueued to. This must match a backend defined in `BACKEND`.

  queue_name

    The name of the queue the `Task` will be enqueued on to. Defaults to `"default"`. This must match a queue defined in `QUEUES`, unless `QUEUES` is set to `[]`.

  run_after

    The earliest time the `Task` will be executed. This can be a `timedelta`, which is used relative to the current time, a timezone-aware `datetime`, or `None` if not constrained. Defaults to `None`.

    The backend must have `supports_defer` set to `True` to use this feature. Otherwise, `InvalidTask` is raised.

  name

    The name of the function decorated with `task()`. This name is not necessarily unique.

  using(*, priority=None, backend=None, queue_name=None, run_after=None)

    Creates a new `Task` with modified defaults. The existing `Task` is left unchanged.

    `using` allows modifying the following attributes:

    - `priority`

    - `backend`

    - `queue_name`

    - `run_after`

    See modifying Tasks for usage examples.

  enqueue(*args, **kwargs)

    Enqueues the `Task` to the `Task` backend for later execution.

    Arguments are passed to the `Task`’s function after a round-trip through a `json.dumps()`/`json.loads()` cycle. Hence, all arguments must be JSON-serializable and preserve their type after the round-trip.

    If the `Task` is not valid according to the backend, `InvalidTask` is raised.

    See enqueueing Tasks for usage examples.

  aenqueue(*args, **kwargs)

    The `async` variant of `enqueue`.

  get_result(result_id)

    Retrieves a result by its id.

    If the result does not exist, `TaskResultDoesNotExist` is raised. If the result is not the same type as the current Task, `TaskResultMismatch` is raised. If the backend does not support `get_result()`, `NotImplementedError` is raised.

  aget_result(*args, **kwargs)

    The `async` variant of `get_result`.

## Task context

class TaskContext

  Contains context for the running `Task`. Context only passed to a `Task` if it was defined with `takes_context=True`.

  Attributes of `TaskContext` cannot be modified.

  task_result

    The `TaskResult` currently being run.

  attempt

    The number of the current execution attempts for this Task, starting at 1.

## Task results

class TaskResultStatus

  An Enum representing the status of a `TaskResult`.

  READY

    The `Task` has just been enqueued, or is ready to be executed again.

  RUNNING

    The `Task` is currently being executed.

  FAILED

    The `Task` raised an exception during execution, or was unable to start.

  SUCCESSFUL

    The `Task` has finished executing successfully.

class TaskResult

  The `TaskResult` stores the information about a specific execution of a `Task`.

  Attributes of `TaskResult` cannot be modified.

  task

    The `Task` the result was enqueued for.

  id

    A unique identifier for the result, which can be passed to `Task.get_result()`.

    The format of the id will depend on the backend being used. Task result ids are always strings less than 64 characters.

    See Task results for more details.

  status

    The `status` of the result.

  enqueued_at

    The time when the `Task` was enqueued.

  started_at

    The time when the `Task` began execution, on its first attempt.

  last_attempted_at

    The time when the most recent `Task` run began execution.

  finished_at

    The time when the `Task` finished execution, whether it failed or succeeded.

  backend

    The backend the result is from.

  errors

    A list of `TaskError` instances for the errors raised as part of each execution of the Task.

  return_value

    The return value from the `Task` function.

    If the `Task` did not finish successfully, `ValueError` is raised.

    See return values for usage examples.

  refresh()

    Refresh the result’s attributes from the queue store.

  arefresh()

    The `async` variant of `TaskResult.refresh()`.

  is_finished

    Whether the `Task` has finished (successfully or not).

  attempts

    The number of times the Task has been run.

    If the task is currently running, it does not count as an attempt.

  worker_ids

    The ids of the workers which have executed the Task.

### Task errors

class TaskError

  Contains information about the error raised during the execution of a `Task`.

  traceback

    The traceback (as a string) from the raised exception when the `Task` failed.

  exception_class

    The exception class raised when executing the `Task`.

## Backends

Backends handle how Tasks are stored and executed. All backends share a common interface defined by `BaseTaskBackend`, which specifies the core methods for enqueueing Tasks and retrieving results.

### Base backend

class BaseTaskBackend

  `BaseTaskBackend` is the parent class for all Task backends.

  options

    A dictionary of extra parameters for the Task backend. These are provided using the `OPTIONS` setting.

  enqueue(task, args, kwargs)

    Task backends which subclass `BaseTaskBackend` should implement this method as a minimum.

    When implemented, `enqueue()` enqueues the `task`, a `Task` instance, for later execution. `args` are the positional arguments and `kwargs` are the keyword arguments to be passed to the `task`. Returns a `TaskResult`.

  aenqueue(task, args, kwargs)

    The `async` variant of `BaseTaskBackend.enqueue()`.

  get_result(result_id)

    Retrieve a result by its id. If the result does not exist, `TaskResultDoesNotExist` is raised.

    If the backend does not support `get_result()`, `NotImplementedError` is raised.

  aget_result(result_id)

    The `async` variant of `BaseTaskBackend.get_result()`.

  validate_task(task)

    Validates whether the provided `Task` is able to be enqueued using the backend. If the Task is not valid, `InvalidTask` is raised.

#### Feature flags

Some backends may not support all features Django provides. It’s possible to identify the supported functionality of a backend, and potentially change behavior accordingly.

BaseTaskBackend.supports_defer

  Whether the backend supports enqueueing Tasks to be executed after a specific time using the `run_after` attribute.

BaseTaskBackend.supports_async_task

  Whether the backend supports enqueueing async functions (coroutines).

BaseTaskBackend.supports_get_result

  Whether the backend supports retrieving `Task` results from another thread after they have been enqueued.

BaseTaskBackend.supports_priority

  Whether the backend supports executing Tasks as ordered by their `priority`.

The below table notes which of the built-in backends support which features:

Feature | `DummyBackend` | `ImmediateBackend`
--- | --- | ---
`supports_defer` | Yes | No
`supports_async_task` | Yes | Yes
`supports_get_result` | No | No [1]
`supports_priority` | Yes [2] | Yes [3]

### Available backends

Django includes only development and testing backends. These support local execution and inspection, for production ready backends refer to Configuring a Task backend.

#### Immediate backend

class ImmediateBackend

  The immediate backend executes Tasks immediately, rather than in the background.

#### Dummy backend

class DummyBackend

  The dummy backend does not execute enqueued Tasks. Instead, it stores task results for later inspection.

  results

    A list of results for the enqueued Tasks, in the order they were enqueued.

  clear()

    Clears the list of stored results.

## Exceptions

exception InvalidTask

  Raised when the `Task` attempting to be enqueued is invalid.

exception InvalidTaskBackend

  Raised when the requested `BaseTaskBackend` is invalid.

exception TaskResultDoesNotExist

  Raised by `get_result()` when the provided `result_id` does not exist.

exception TaskResultMismatch

  Raised by `get_result()` when the provided `result_id` is for a different Task than the current Task.

Footnotes

[1]

The `ImmediateBackend` doesn’t officially support `get_result()`, despite implementing the API, since the result cannot be retrieved from a different thread.

[2]

The `DummyBackend` has `supports_priority=True` so that it can be used as a drop-in replacement in tests. Since this backend never executes Tasks, the `priority` value has no effect.

[3]

The `ImmediateBackend` has `supports_priority=True` so that it can be used as a drop-in replacement in tests. Because Tasks run as soon as they are scheduled, the `priority` value has no effect.