• 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
  • Choose a message broker , configure it and install the appropriate client library.

  • Run Django Q cluster in order to handle tasks async:

    $ python qcluster


Django Q is tested for Python 3.7, 3.8 and 3.9

  • Django

    Django Q aims to use as much of Django’s standard offerings as possible The code is tested against Django versions 2.2.x and 3.2.x. Please note that Django versions below 2.0 do not support Python 3.7

  • Django-picklefield

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

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


  • Redis-py client by Andy McCurdy is used to interface with both the Redis and Disque brokers:

    $ pip install redis
  • Psutil python system and process utilities module by Giampaolo Rodola’, is an optional requirement and adds cpu affinity settings to the cluster:

    $ pip install psutil
  • Hiredis parser. This C library maintained by the core Redis team is faster than the standard PythonParser during high loads:

    $ pip install hiredis
  • Boto3 is used for the Amazon SQS broker in favor of the now deprecating boto library:

    $ pip install boto3
  • Iron-mq is the official python binding for the IronMQ broker:

    $ pip install iron-mq
  • Pymongo is needed if you want to use MongoDB as a message broker:

    $ pip install pymongo
  • Redis server is the default broker for Django Q. It provides the best performance and does not require Django’s cache framework for monitoring.

  • Disque server is based on Redis by the same author, but focuses on reliable queues. Currently in Alpha, but highly recommended. You can either build it from source or use it on Heroku through the Tynd beta.

  • MongoDB is a highly scalable NoSQL database which makes for a very fast and reliably persistent at-least-once message broker. Usually available on most PaaS providers.

  • Pyrollbar is an error notifier for Rollbar which lets you manage your worker errors in one place. Needs a Rollbar account and access key:

    $ pip install rollbar
  • Croniter is an optional package that is used to parse cron expressions for the scheduler:

    $ pip install croniter


  • django-q-rollbar is a Rollbar error reporter:

    $ pip install django-q[rollbar]
  • django-q-sentry is a Sentry error reporter:

    $ pip install django-q[sentry]
  • django-q-email is a compatible Django email backend that will automatically async queue your emails.


Django Q is still a young project. If you do find any incompatibilities please submit an issue on github.


Running Django Q on OS X should work fine, except for the following known issues:

  • multiprocessing.Queue.qsize() is not supported. This leads to the monitor not reporting the internal queue size of clusters running under OS X.
  • CPU count through multiprocessing.cpu_count() does not work. Installing psutil provides Django Q with an alternative way of determining the number of CPU’s on your system
  • CPU affinity is provided by psutil which at this time does not support this feature on OSX. The code however is aware of this and will fake the CPU affinity assignment in the logs without actually assigning it. This way you can still develop with this setting.


The cluster and worker multiprocessing code depend on the OS’s ability to fork, unfortunately forking is not supported under windows. You should however be able to develop and test without the cluster by setting the sync option to True in the configuration. This will run all async calls inline through a single cluster worker without the need for forking. Other known issues are:

  • os.getppid() is only supported under windows since Python 3.2. If you use an older version you need to install psutil as an alternative.
  • CPU count through multiprocessing.cpu_count() occasionally fails on servers. Installing psutil provides Django Q with an alternative way of determining the number of CPU’s on your system
  • The monitor and info commands rely on the Curses package which is not officially supported on windows. There are however some ports available like this one by Christoph Gohlke.


The code is always tested against the latest version Python 3 and we try to stay compatible with the last two versions of each. Current tests are performed with 3.7 and 3.8 If you do encounter any regressions with earlier versions, please submit an issue on github


Django releases before 1.11 are not supported on Python 3.6 Django releases before 2.0 are not supported on Python 3.7

Open-source packages

Django Q is always tested with the latest versions of the required and optional Python packages. We try to keep the dependencies as up to date as possible. You can reference the requirements file to determine which versions are currently being used for tests and development.


We strive to be compatible with last two major version of Django. At the moment this means we support the 2.2.x and 3.1.x releases.

Since we are now no longer supporting Python 2, we can also not support older versions of Django that do not support Python >= 3.6 For this you can always use older releases, but they are no longer maintained.