• Install the latest version with pip:

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

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

    $ python migrate
  • Make sure you have a Redis server running somewhere


Configuration is handled via the Q_ClUSTER dictionary in your

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


Used to differentiate between projects using the same Redis server. Defaults to 'default'. This can be useful if you have several projects using the same Redis server.


Tasks are encrypted. When a worker encounters a task it can not decrypt, it will be discarded.


The number of workers to use in the cluster. Defaults to CPU count of the current host, but can be set to a custom number.


The number of tasks a worker will process before recycling . Useful to release memory resources on a regular basis. Defaults to 500.


The number of seconds a worker is allowed to spend on a task before it’s terminated. Defaults to None, meaning it will never time out. Set this to something that makes sense for your project.


Compresses task packages to Redis. Useful for large payloads, but can add overhead when used with many small packages. Defaults to False


Limits the amount of successful tasks saved to Django. - Set to 0 for unlimited. - Set to -1 for no success storage at all. - Defaults to 250 - Failures are always saved.


The label used for the Django Admin page. Defaults to 'Django Q'


Connection settings for Redis. Defaults:

redis: {
    'host': 'localhost',
    'port': 6379,
    'db': 0,
    'password': None,
    'socket_timeout': None,
    'charset': 'utf-8',
    'errors': 'strict',
    'unix_socket_path': None

For more information on these settings please refer to the Redis-py documentation


If you are already using django-redis for your caching, you can take advantage of its excellent connection backend by supplying the name of the cache connection you want to use:

# example django-redis connection
    'name': 'DJRedis',
    'workers': 4,
    'timeout': 90,
    'django_redis: 'default'


Django Q uses your SECRET_KEY to encrypt task packages and prevent task crossover. So make sure you have it set up in your Django settings.


Django Q is tested for Python 2.7 and 3.4

  • Django

    Django Q aims to use as much of Django’s standard offerings as possible The code is tested against Django version 1.7.8 and 1.8.2.

  • Django-picklefield

    Used to store args, kwargs and result objects in the database.

  • Redis-py

    Andy McCurdy’s excellent Redis python client.

  • Arrow

    The scheduler uses Chris Smith’s wonderful project to determine correct dates in the future.

  • Blessed

    This feature-filled fork of Erik Rose’s blessings project provides the terminal layout of the monitor.


Install the Hiredis parser:

$ pip install hiredis

This C library maintained by the core Redis team is faster than the standard PythonParser during high loads.