{"id":4516,"library":"django-rq","title":"Django-RQ","description":"Django-RQ is a simple app that provides seamless integration for RQ (Redis Queue) with the Django framework. It allows developers to configure Redis queues directly within Django's settings, enqueue tasks, and manage background workers efficiently. The library is actively maintained, currently at version 4.1.0, and typically releases updates as new features or compatibility fixes for Django and RQ are introduced.","status":"active","version":"4.1.0","language":"en","source_language":"en","source_url":"https://github.com/rq/django-rq","tags":["django","rq","redis","queue","background tasks","async"],"install":[{"cmd":"pip install django-rq","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core framework integration.","package":"Django"},{"reason":"The underlying Redis Queue library.","package":"rq"},{"reason":"Python client for Redis, required by RQ.","package":"redis"},{"reason":"Optional: For using existing Redis cache connection info.","package":"django-redis","optional":true},{"reason":"Optional: For scheduled job capabilities.","package":"rq-scheduler","optional":true},{"reason":"Optional: For Prometheus metrics endpoint in admin.","package":"prometheus-client","optional":true}],"imports":[{"note":"Decorator for defining an RQ job.","symbol":"job","correct":"from django_rq import job"},{"note":"Directly enqueues a job to the default queue.","symbol":"enqueue","correct":"import django_rq\ndjango_rq.enqueue(func, *args, **kwargs)"},{"note":"Retrieves an RQ Queue instance by name for more advanced operations.","symbol":"get_queue","correct":"import django_rq\nqueue = django_rq.get_queue('queue_name')"},{"note":"Retrieves the Redis connection for a given queue.","symbol":"get_connection","correct":"import django_rq\nredis_conn = django_rq.get_connection('queue_name')"},{"note":"Retrieves an RQ Scheduler instance (requires rq-scheduler).","symbol":"get_scheduler","correct":"import django_rq\nscheduler = django_rq.get_scheduler('queue_name')"}],"quickstart":{"code":"import os\nimport time\nfrom django.conf import settings\nfrom django.apps import apps\n\n# Minimal Django setup for demonstration\nif not apps.ready:\n    settings.configure(\n        INSTALLED_APPS=[\n            'django.contrib.admin',\n            'django.contrib.auth',\n            'django.contrib.contenttypes',\n            'django.contrib.sessions',\n            'django.contrib.messages',\n            'django.contrib.staticfiles',\n            'django_rq',\n        ],\n        RQ_QUEUES={\n            'default': {\n                'HOST': os.environ.get('REDIS_HOST', 'localhost'),\n                'PORT': int(os.environ.get('REDIS_PORT', 6379)),\n                'DB': int(os.environ.get('REDIS_DB', 0)),\n                'PASSWORD': os.environ.get('REDIS_PASSWORD', None),\n                'DEFAULT_TIMEOUT': 360,\n            }\n        },\n        SECRET_KEY='a-very-secret-key',\n        DEBUG=True,\n        ROOT_URLCONF=__name__,\n        TEMPLATES=[\n            {\n                'BACKEND': 'django.template.backends.django.DjangoTemplates',\n                'APP_DIRS': True,\n            },\n        ],\n    )\n    import django\n    django.setup()\n\nfrom django_rq import job\nimport django_rq\n\n@job\ndef my_background_task(arg1, arg2):\n    \"\"\"A simple task to be run in the background.\"\"\"\n    print(f\"Running task with {arg1} and {arg2}...\")\n    time.sleep(2) # Simulate work\n    result = arg1 + arg2\n    print(f\"Task finished. Result: {result}\")\n    return result\n\n# Enqueue the task\nprint(\"Enqueuing task...\")\njob_id = my_background_task.delay(10, 20)\nprint(f\"Task enqueued with ID: {job_id}\")\n\n# To run the worker, you would typically use:\n# python manage.py rqworker default\n# (Ensure a Redis server is running)\n","lang":"python","description":"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]"},"warnings":[{"fix":"Remove `include('django_rq.urls')` from your `urls.py`. Update `AUTOCOMMIT` in `RQ_QUEUES` to `COMMIT_MODE` as per documentation. [4, 12]","message":"In 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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update any code referencing `FailedQueue` to `FailedJobRegistry`. [4]","message":"Version 2.0 introduced backward incompatible changes. `FailedQueue` was replaced by `FailedJobRegistry`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `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]","message":"RQ version 1.14 removed `use_connection()`, which caused issues with older versions of `django-rq`.","severity":"breaking","affected_versions":"<=3.x.x (if used with RQ >=1.14)"},{"fix":"Always use `python manage.py rqworker [queue_names]` or ensure `DJANGO_SETTINGS_MODULE` is correctly set if running workers outside of `manage.py`. [11]","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Double-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]","message":"For 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}