Install & Compatibility
Where this runs
tested against v4.1.1 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 75.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.3s · import 0.000s · 76MB
75MB installed
● package 75MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
job
✓ from django_rq import job
✗ from django_rq import job
This quickstart demonstrates how to configure Django-RQ, define a background task using the `@job` decorator, and enqueue it. It includes a minimal Django settings setup for standalone execution. To run this, you need a running Redis server and then execute the script, followed by `python manage.py rqworker default` in a separate terminal to process the job. [2, 3, 6]
import os
import time
from django.conf import settings
from django.apps import apps
# Minimal Django setup for demonstration
if not apps.ready:
settings.configure(
INSTALLED_APPS=[
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'django_rq',
],
RQ_QUEUES={
'default': {
'HOST': os.environ.get('REDIS_HOST', 'localhost'),
'PORT': int(os.environ.get('REDIS_PORT', 6379)),
'DB': int(os.environ.get('REDIS_DB', 0)),
'PASSWORD': os.environ.get('REDIS_PASSWORD', None),
'DEFAULT_TIMEOUT': 360,
}
},
SECRET_KEY='a-very-secret-key',
DEBUG=True,
ROOT_URLCONF=__name__,
TEMPLATES=[
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'APP_DIRS': True,
},
],
)
import django
django.setup()
from django_rq import job
import django_rq
@job
def my_background_task(arg1, arg2):
"""A simple task to be run in the background."""
print(f"Running task with {arg1} and {arg2}...")
time.sleep(2) # Simulate work
result = arg1 + arg2
print(f"Task finished. Result: {result}")
return result
# Enqueue the task
print("Enqueuing task...")
job_id = my_background_task.delay(10, 20)
print(f"Task enqueued with ID: {job_id}")
# To run the worker, you would typically use:
# python manage.py rqworker default
# (Ensure a Redis server is running)
django-admin --version
Debug
Known issues
breakingIn version 4.0, Django-RQ automatically integrates with Django's admin backend, removing the need for manual URL configuration. The `AUTOCOMMIT` setting was also replaced by `COMMIT_MODE`. Legacy Sentry integration was removed.fixRemove `include('django_rq.urls')` from your `urls.py`. Update `AUTOCOMMIT` in `RQ_QUEUES` to `COMMIT_MODE` as per documentation. [4, 12] affects: >=4.0.0
breakingVersion 2.0 introduced backward incompatible changes. `FailedQueue` was replaced by `FailedJobRegistry`.fixUpdate any code referencing `FailedQueue` to `FailedJobRegistry`. [4]
affects: >=2.0.0
breakingRQ version 1.14 removed `use_connection()`, which caused issues with older versions of `django-rq`.fixEnsure `django-rq` is updated to a version compatible with your `rq` installation, ideally `django-rq` >= 4.0.0 which supports `rq` >= 2.2. [4, 12, 13]
affects: <=3.x.x (if used with RQ >=1.14)
gotchaWhen running `rqworker`, it must be executed within a Django context to properly access settings. If not using `python manage.py rqworker`, you might need to set the `DJANGO_SETTINGS_MODULE` environment variable.fixAlways use `python manage.py rqworker [queue_names]` or ensure `DJANGO_SETTINGS_MODULE` is correctly set if running workers outside of `manage.py`. [11]
affects: All versions
gotchaFor optimal performance and to avoid issues, ensure your Redis instance is properly configured and accessible from both your Django application and RQ workers. Misconfigured Redis connections are a common source of problems.fixDouble-check your `RQ_QUEUES` settings in `settings.py`, especially `HOST`, `PORT`, `DB`, and `PASSWORD` (if applicable). Use tools like `redis-cli` to verify connectivity. [6, 14]
affects: All versions
Upgrade
Version history
4.1.1latest on PyPI · released Jul 4, 2026
Audit
Dependencies
DjangorequiredCore framework integration.
rqrequiredThe underlying Redis Queue library.
redisrequiredPython client for Redis, required by RQ.
django-redisoptionalOptional: For using existing Redis cache connection info.
rq-scheduleroptionalOptional: For scheduled job capabilities.
prometheus-clientoptionalOptional: For Prometheus metrics endpoint in admin.