Django-RQ

Django-RQ is a Django application that layers first-class RQ (Redis Queue) integration onto your project. You declare your queues in Django’s settings.py, then enqueue work with familiar helpers or a simple @job decorator without wiring up Redis connections by hand.

Beyond enqueueing, it ships management commands for running workers, a dashboard that plugs directly into the Django admin for monitoring queues, jobs, and workers, plus support for scheduled and cron-style jobs, Prometheus metrics, and reuse of your existing django-redis cache connection.

What You Get

• Declarative queue configuration in Django’s settings.py, including Redis Sentinel and cache-connection reuse
• An @job decorator and enqueue/get_queue helpers that turn any callable into a background task
• Management commands (rqworker, rqworker-pool, rqscheduler, rqstats, rqsuspend) for running and controlling workers
• A monitoring dashboard integrated into the Django admin with queue, job registry, and worker views
• Support for scheduled jobs, RQ’s CronScheduler, Prometheus metrics, and JSON queue statistics

Common Use Cases

• Offloading slow work such as sending emails, generating reports, or calling external APIs out of the request/response cycle
• Running periodic and scheduled tasks with RQ’s built-in scheduler or cron configuration
• Monitoring queue depth, failed jobs, and worker health directly from the Django admin

Under The Hood

Architecture - Django-RQ is a thin, well-factored integration layer over the RQ library. Configuration is read from the RQ_QUEUES/RQ settings dict by django_rq/settings.py and turned into connections in connection_utils.py, while queues.py builds Queue instances and implements commit modes (auto, request_finished, on_db_commit) that let enqueue calls fire immediately or defer until a database transaction commits via thread_queue.py. The @job decorator in decorators.py wraps RQ’s own decorator, workers.py adds worker/worker-pool construction, and views.py plus stats_views.py and cron_views.py render the admin-embedded dashboard and JSON/Prometheus statistics; management commands expose worker, scheduler, and stats operations.

Tech Stack - Pure Python targeting Python 3.10+, built with the Hatchling backend. Runtime dependencies are Django (4.2+), rq (2.6.1+), and redis (3.5+), with optional prometheus_client for metrics. Development tooling includes Ruff for linting/formatting and mypy for type checking, and the package ships a py.typed marker for typed distribution.

Code Quality - The codebase is compact (~2,300 lines across the django_rq package) and cleanly separated by concern. It ships extensive type hints (including Protocol/overload definitions for the job decorator) and a py.typed marker, is checked with mypy and Ruff, and carries a substantial test suite under tests/ covering connections, views, admin integration, commit modes, cron, and Prometheus metrics, plus an integration_test harness.

API Design - The public surface is deliberately small and idiomatic for Django: configure queues in settings.py, then use enqueue, get_queue, get_worker, and the @job decorator. The decorator mirrors RQ’s own signature, monitoring drops into the existing Django admin with no extra routing, and management commands follow Django conventions, so the learning curve for anyone who knows Django and RQ is minimal.