# Django 5.2.7 documentation

# Tasks

New in Django 6.0.

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

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

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