# django-rq: Redis background jobs in a Django project

> django-rq connects Django applications to RQ queues backed by Redis, with queue configuration in `settings.py`, worker commands, decorators, and an admin dashboard. It fits applications that need background processing, but it requires a separately operated Redis service and worker processes.

**rq/django-rq** — A simple app that provides django integration for RQ (Redis Queue)

- Repository: https://github.com/rq/django-rq
- Stars: 1,954 · Forks: 294
- Language: Python
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/rq-django-rq

## Where django-rq fits in a Django application

django-rq addresses a specific boundary in Django applications: work that should not run inside a web request. RQ stores jobs in Redis and executes them through worker processes. django-rq makes that queue accessible through Django settings and management commands rather than requiring the application to construct every RQ and Redis connection itself.

The intended users are Python developers building with Django 4.2 or later and Redis-backed services that need tasks such as deferred processing, scheduled jobs, or other work outside the request cycle. The package does not define business workflows, retry policies, or job payloads. Those responsibilities remain with RQ, the application, and whatever function an application enqueues.

This distinction matters when choosing django-rq. It is not a complete workflow engine by itself. The repository presents it as a Django integration layer for RQ, with utilities for retrieving queues and workers, decorating callables, exposing queues in the Django admin, and optionally publishing Prometheus metrics. The project requires Python 3.10 or later, Django 4.2 or later, RQ 2.6.1 or later, and redis 3.5 or later.

## Queue configuration and Redis connection paths

Queue definitions live in Django's `settings.py` under `RQ_QUEUES`. Each named definition can specify a host, port, database number, credentials, job timeout, result retention, or a Redis URL. The configuration also supports Redis Sentinel through `SENTINELS`, `MASTER_NAME`, `SENTINEL_KWARGS`, and connection arguments such as `SOCKET_TIMEOUT` and `CONNECTION_KWARGS`.

The integration supports several connection shapes. A direct Redis server can be described with `HOST`, `PORT`, and `DB`. A managed service can be represented by `URL`. Sentinel deployments describe the monitored Redis services separately from the master name. Additional Redis client arguments can be passed through `REDIS_CLIENT_KWARGS`. This flexibility matters because Django-RQ does not require every deployment to expose Redis in the same way.

Queue names then form the application-facing routing boundary. The README shows queues named `default`, `high`, and `low`, which can represent workload priorities or separate processing domains. `django_rq.get_queue(name)` returns an RQ `Queue` instance for the selected definition, while `django_rq.get_connection(name)` returns the corresponding Redis connection. A shared Redis connection can be passed to `get_queue` through its `connection` argument. The README presents this as a way to limit repeated connection objects, which is relevant when an application creates queue instances frequently.

## Enqueueing functions and selecting worker queues

Jobs are queued through small helper functions or a decorator. `django_rq.enqueue(func, foo, bar=baz)` submits a function to the `default` queue. For explicit routing, `get_queue('high')` retrieves a named queue and its `enqueue` method submits the function there.

The decorator offers a more local API. Applying `@job` makes `long_running_func.delay()` enqueue the function in the default queue. `@job('high')` selects the `high` queue, and decorator arguments accepted by RQ can set job properties such as `timeout`. The README also documents queue-level overrides for `default_timeout`, `is_async`, and `commit_mode`, including `commit_mode='on_db_commit'`.

Workers are separate from the Django web process. The `rqworker` management command starts workers for named queues:

```bash
python manage.py rqworker high default low
```

A worker that should exit after processing available work can be started in burst mode:

```bash
python manage.py rqworker high default low --burst
```

The command line determines which queues a worker consumes. This is an operational boundary, not a hidden automatic integration: an application can enqueue into a queue that has no worker consuming it, and the jobs will remain in Redis. The README does not document automatic worker provisioning or a rollback command, so deployment must account for worker lifecycle separately.

## Django admin, standalone URLs, and Prometheus views

Version 4.0 introduced automatic Django admin integration. Once `django_rq` is in `INSTALLED_APPS`, the README says the dashboard is available at `/admin/django_rq/dashboard/`. It provides queue statistics, monitoring information, browsers for scheduled, started, finished, failed, and deferred job registries, and worker management.

A Prometheus metrics endpoint is available when `prometheus_client` is installed. The package declares that dependency as the optional `prometheus` extra, rather than making metrics a mandatory part of every installation. A deployment that does not install the extra should not assume that the metrics view will have its metric backend.

Applications can disable the admin sidebar link with `RQ_SHOW_ADMIN_LINK = False`. For deployments that do not want the views nested under Django admin, the README documents a standalone URL prefix:

```python
# urls.py
urlpatterns += [
    path('django-rq/', include('django_rq.urls'))
]
```

That changes the standalone location to `/django-rq/`. Templates should use the `rq_url` tag rather than hard-coded URL prefixes because the tag resolves either the admin namespace or the standalone namespace.

```django
{% load django_rq %}
<a href="{% rq_url 'home' %}">Django RQ</a>
```

The dual URL arrangement is useful for sites that want operations pages outside admin. It also means URL availability and access control should be checked in the actual Django URL configuration.

## Installation and first queue submission

The documented installation starts with the PyPI package, followed by registration in `INSTALLED_APPS` and a queue definition in Django settings.

```bash
pip install django-rq
```

Add the application to the project settings:

```python
INSTALLED_APPS = (
    # other apps
    "django_rq",
)
```

Define at least a Redis-backed queue:

```python
RQ_QUEUES = {
    'default': {
        'HOST': 'localhost',
        'PORT': 6379,
        'DB': 0,
        'DEFAULT_TIMEOUT': 360,
        'DEFAULT_RESULT_TTL': 800,
    },
}
```

A first submission can use the default helper, but the function must be importable by the worker process. The README gives this API shape:

```python
import django_rq

django_rq.enqueue(func, foo, bar=baz)
```

After the enqueue call, start a worker for the named queues:

```bash
python manage.py rqworker high default low
```

The worker process is the component that executes the job. The README does not describe a required Redis startup command, migration step, or result polling API for this basic path, so those details should not be inferred from the integration itself.

## Limits, alternatives, licensing, and maintenance

The main limitation is operational coupling. Redis is the queue backend, so the application needs a reachable Redis service, sensible connection settings, and worker processes that remain available for the queues being consumed. The README does not document automatic retries, dead-letter handling, or rollback behavior for jobs, and it does not promise that every Redis deployment mode is interchangeable.

django-rq is also not the right choice when the requirement is to avoid running a Redis service or when background jobs must survive a particular broker failure under a different persistence model. RQ itself is the closer alternative when the application does not need Django settings, Django admin integration, or `django_rq` helpers. The concrete distinction here is scope: django-rq integrates RQ with Django, while direct RQ use leaves Django-specific configuration and admin behavior outside the integration layer.

The package uses the MIT license, and `pyproject.toml` identifies the license file as `LICENSE.txt`. Review that file and the dependency licenses separately for compliance requirements. The repository is not archived, and its last push was on 2026-10-12. Recent releases include v4.2, v4.1.1, and v4.1. Upgrade planning should account for the documented minimum versions: Python 3.10, Django 4.2, RQ 2.6.1, and redis 3.5.

## Conclusion

Django teams that already use Redis and need straightforward background job execution should consider django-rq. Projects that require broker-independent persistence, managed deployment, or documentation for automatic rollback should first verify those needs against RQ, Redis operations, and the project documentation. The first adoption check is whether every intended job has a stable Python import path, a deliberate timeout, and an understood result retention policy.

## FAQ

### How do I install django-rq in a Django project?

Install it with `pip install django-rq`, add `"django_rq"` to `INSTALLED_APPS`, and define a queue in `RQ_QUEUES`. The README lists Django 4.2 or later as a requirement, while `pyproject.toml` requires Python 3.10 or later.

### How do I run a django-rq worker?

Run `python manage.py rqworker high default low` to start a worker for the named queues. Add `--burst` when the worker should exit after processing available work.

### How do I enqueue a job to a named django-rq queue?

Retrieve the queue with `django_rq.get_queue('high')`, then call `queue.enqueue(func, foo, bar=baz)`. You can also use `@job('high')` and call the decorated function with `.delay()`.

## Sources

- [Issues](https://github.com/rq/django-rq/issues)
- [License: MIT](https://github.com/rq/django-rq/blob/master/LICENSE)
- [README](https://github.com/rq/django-rq/blob/master/README.md)
- [Releases](https://github.com/rq/django-rq/releases)
- [rq/django-rq on GitHub](https://github.com/rq/django-rq)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rq-django-rq