Skip to main content

A multiprocessing distributed task queue for Django

Project description

Q logo

A multiprocessing distributed task queue for Django

image0 image1 Documentation Status image2


  • Multiprocessing worker pool
  • Asynchronous tasks
  • Scheduled, cron and repeated tasks
  • Signed and compressed packages
  • Failure and success database or cache
  • Result hooks, groups and chains
  • Django Admin integration
  • PaaS compatible with multiple instances
  • Multi cluster monitor
  • Redis, Disque, IronMQ, SQS, MongoDB or ORM
  • Rollbar and Sentry support


Tested with: Python 3.7, 3.8, 3.9 Django 2.2.X and 3.2.X


Since Python 3.7 async became a reserved keyword and was refactored to async_task


  • Install the latest version with pip:

    $ pip install django-q
  • Add django_q to your INSTALLED_APPS in your projects

        # other apps
  • Run Django migrations to create the database tables:

    $ python migrate
  • Choose a message broker , configure and install the appropriate client library.

Read the full documentation at


All configuration settings are optional. e.g:

# example
    'name': 'myproject',
    'workers': 8,
    'recycle': 500,
    'timeout': 60,
    'compress': True,
    'cpu_affinity': 1,
    'save_limit': 250,
    'queue_limit': 500,
    'label': 'Django Q',
    'redis': {
        'host': '',
        'port': 6379,
        'db': 0, }

For full configuration options, see the configuration documentation.

Management Commands

Start a cluster with:

$ python qcluster

Monitor your clusters with:

$ python qmonitor

Monitor your clusters’ memory usage with:

$ python qmemory

Check overall statistics with:

$ python qinfo

Creating Tasks

Use async_task from your code to quickly offload tasks:

from django_q.tasks import async_task, result

# create the task
async_task('math.copysign', 2, -2)

# or with a reference
import math.copysign

task_id = async_task(copysign, 2, -2)

# get the result
task_result = result(task_id)

# result returns None if the task has not been executed yet
# you can wait for it
task_result = result(task_id, 200)

# but in most cases you will want to use a hook:

async_task('math.modf', 2.5, hook='hooks.print_result')

def print_result(task):

For more info see Tasks


Schedules are regular Django models. You can manage them through the Admin page or directly from your code:

# Use the schedule function
from django_q.tasks import schedule

         2, -2,

# Or create the object directly
from django_q.models import Schedule


# Run a task every 5 minutes, starting at 6 today
# for 2 hours
import arrow

         3, 4,
         next_run=arrow.utcnow().replace(hour=18, minute=0))

# Use a cron expression
         3, 4,
         cron = '0 22 * * 1-5')

For more info check the Schedules documentation.


To run the tests you will need the following in addition to install requirements:

Or you can use the included Docker Compose file.

The following commands can be used to run the tests:

# Create virtual environment
python -m venv venv

# Install requirements
venv/bin/pip install -r requirements.txt

# Install test dependencies
venv/bin/pip install pytest pytest-django

# Install django-q
venv/bin/python develop

# Run required services (you need to have docker-compose installed)
docker-compose -f test-services-docker-compose.yaml up -d

# Run tests

# Stop the services required by tests (when you no longer plan to run tests)
docker-compose -f test-services-docker-compose.yaml down


Currently available in English, German and French. Translation pull requests are always welcome.


  • Better tests and coverage
  • Less dependencies?


Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-q, version 1.3.9
Filename, size File type Python version Upload date Hashes
Filename, size django_q-1.3.9-py3-none-any.whl (90.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-q-1.3.9.tar.gz (72.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page