Install & Compatibility
Where this runs
tested against v1.10.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 67.3MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 3.6s · import 0.000s · 68MB
67MB installed
● package 67MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
async_task
✓ from django_q.tasks import async_task
✗ from django_q import async_task
To get started, add 'django_q' to your `INSTALLED_APPS` and configure `Q_CLUSTER` in your `settings.py`. Ensure you run `python manage.py migrate` to create necessary database tables. Define your task functions and enqueue them using `async_task`. Finally, start the Q2 cluster with `python manage.py qcluster` to process tasks in the background. The example above demonstrates a basic setup and how to enqueue a task, assuming a Django project structure.
import os
import django
from django.conf import settings
# Minimal Django setup if running outside a full Django environment
if not settings.configured:
settings.configure(
INSTALLED_APPS=[
'django_q',
# Add other apps if needed
],
DATABASES={
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': ':memory:',
}
},
Q_CLUSTER={
'name': 'myproject',
'workers': 4,
'timeout': 90,
'compress': True,
'save_limit': 250,
'queue_limit': 500,
'cpu_affinity': 1,
'label': 'Django Q2',
'redis': os.environ.get('REDIS_URL', 'redis://localhost:6379/0'),
},
SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-development'),
TIME_ZONE='UTC',
USE_TZ=True,
)
django.setup()
# Your task function (e.g., in a tasks.py file)
def my_long_running_task(iterations):
result = 0
for i in range(iterations):
result += i
return result
# Enqueue the task
from django_q.tasks import async_task
task_id = async_task('my_app.tasks.my_long_running_task', 1000000)
print(f"Task enqueued with ID: {task_id}")
# To run the cluster in a separate terminal:
# python manage.py qcluster
Debug
Known issues
breakingPython 3.8 support was dropped in `django-q2` v1.8.0. Ensure your Python environment is 3.9 or higher when upgrading.fixUpgrade your Python version to 3.9 or newer before upgrading `django-q2` to version 1.8.0 or later.
affects: >=1.8.0
breakingDjango 3.2 and 4.1 support was dropped in `django-q2` v1.7.0. Subsequent versions require Django 4.2 or newer, with v1.9.0 adding support for Django 6.0.fixUpgrade your Django project to version 4.2 or later before upgrading `django-q2` to version 1.7.0 or later.
affects: >=1.7.0
gotchaIf using Redis as your broker, `django-q2` v1.9.0 introduced a fix for compatibility with `redis-py > 5`. Ensure you are on `django-q2` v1.9.0 or higher if using recent `redis-py` versions to avoid potential issues.fixUpgrade `django-q2` to v1.9.0 or newer if you are using `redis-py` version 5 or greater.
affects: <1.9.0 with redis-py > 5
gotchaThe `SECRET_KEY` in your Django settings is crucial as Django Q2 uses it to sign task packages. Without a properly set `SECRET_KEY`, tasks might fail to unpack or execute securely.fixEnsure `SECRET_KEY` is set in your Django settings, especially in production environments.
affects: All
gotchaA bug existed in versions prior to 1.7.0 where setting `max_attempts` to 1 would still result in the task being retried once. This could lead to unexpected duplicate executions.fixUpgrade to `django-q2` v1.7.0 or newer to correctly handle `max_attempts=1`.
affects: <1.7.0
deprecatedThe original `django-q` project is no longer maintained. Users are strongly advised to migrate to `django-q2` for continued support and updates. Migration typically involves uninstalling `django-q` and installing `django-q2`.fixUninstall `django-q` and `pip install django-q2`. Then run `python manage.py migrate`.
affects: Users of `django-q`
Upgrade
Version history
1.10.0latest on PyPI · released May 1, 2026
Audit
Dependencies
DjangorequiredCore framework dependency; version compatibility is crucial. Requires Django >=4.2.
django-picklefieldrequiredUsed to store args, kwargs, and result objects in the database.
redisoptionalRequired if using Redis as the message broker.
psutiloptionalOptional, but recommended for more reliable CPU count detection and better monitoring on some operating systems (e.g., OS X, Windows).