{"id":13416002,"url":"https://github.com/rq/django-rq","last_synced_at":"2026-04-06T00:05:18.827Z","repository":{"id":3293378,"uuid":"4334538","full_name":"rq/django-rq","owner":"rq","description":"A simple app that provides django integration for RQ (Redis Queue)","archived":false,"fork":false,"pushed_at":"2025-04-28T07:29:47.000Z","size":1069,"stargazers_count":1874,"open_issues_count":115,"forks_count":292,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-05-08T00:14:14.457Z","etag":null,"topics":["background-jobs","django","job-queue","python","redis","rq","task-queue"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rq.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"authors.rst","dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["selwin"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":"pypi/django-rq","community_bridge":null,"custom":null}},"created_at":"2012-05-15T10:21:58.000Z","updated_at":"2025-05-01T23:25:39.000Z","dependencies_parsed_at":"2024-01-11T19:17:12.121Z","dependency_job_id":"bac032ec-87a1-4c43-b754-f80c0f67e4ce","html_url":"https://github.com/rq/django-rq","commit_stats":{"total_commits":496,"total_committers":117,"mean_commits":4.239316239316239,"dds":0.592741935483871,"last_synced_commit":"c6c33828b7d7129fab1816ccf20ce1a737308187"},"previous_names":["ui/django-rq"],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rq%2Fdjango-rq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rq%2Fdjango-rq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rq%2Fdjango-rq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rq%2Fdjango-rq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rq","download_url":"https://codeload.github.com/rq/django-rq/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252973669,"owners_count":21834108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["background-jobs","django","job-queue","python","redis","rq","task-queue"],"created_at":"2024-07-30T21:00:53.573Z","updated_at":"2025-12-12T00:46:49.740Z","avatar_url":"https://github.com/rq.png","language":"Python","readme":"=========\nDjango-RQ\n=========\n\n|Build Status|\n\nDjango integration with `RQ \u003chttps://github.com/nvie/rq\u003e`__, a `Redis \u003chttp://redis.io/\u003e`__\nbased Python queuing library. `Django-RQ \u003chttps://github.com/rq/django-rq\u003e`__ is a\nsimple app that allows you to configure your queues in django's ``settings.py``\nand easily use them in your project.\n\n=================\nSupport Django-RQ\n=================\n\nIf you find ``django-rq`` useful, please consider supporting its development via `Tidelift \u003chttps://tidelift.com/subscription/pkg/pypi-django_rq?utm_source=pypi-django-rq\u0026utm_medium=referral\u0026utm_campaign=readme\u003e`_.\n\n============\nRequirements\n============\n\n* `Django \u003chttps://www.djangoproject.com/\u003e`__ (3.2+)\n* `RQ \u003chttps://github.com/nvie/rq\u003e`__\n\n============\nInstallation\n============\n\n* Install ``django-rq`` (or `download from PyPI \u003chttp://pypi.python.org/pypi/django-rq\u003e`__):\n\n.. code-block:: python\n\n    pip install django-rq\n\n* Add ``django_rq`` to ``INSTALLED_APPS`` in ``settings.py``:\n\n.. code-block:: python\n\n    INSTALLED_APPS = (\n        # other apps\n        \"django_rq\",\n    )\n\n* Configure your queues in django's ``settings.py``:\n\n.. code-block:: python\n\n    RQ_QUEUES = {\n        'default': {\n            'HOST': 'localhost',\n            'PORT': 6379,\n            'DB': 0,\n            'USERNAME': 'some-user',\n            'PASSWORD': 'some-password',\n            'DEFAULT_TIMEOUT': 360,\n            'DEFAULT_RESULT_TTL': 800,\n            'REDIS_CLIENT_KWARGS': {    # Eventual additional Redis connection arguments\n                'ssl_cert_reqs': None,\n            },\n        },\n        'with-sentinel': {\n            'SENTINELS': [('localhost', 26736), ('localhost', 26737)],\n            'MASTER_NAME': 'redismaster',\n            'DB': 0,\n            # Redis username/password\n            'USERNAME': 'redis-user',\n            'PASSWORD': 'secret',\n            'SOCKET_TIMEOUT': 0.3,\n            'CONNECTION_KWARGS': {  # Eventual additional Redis connection arguments\n                'ssl': True\n            },\n            'SENTINEL_KWARGS': {    # Eventual Sentinel connection arguments\n                # If Sentinel also has auth, username/password can be passed here\n                'username': 'sentinel-user',\n                'password': 'secret',\n            },\n        },\n        'high': {\n            'URL': os.getenv('REDISTOGO_URL', 'redis://localhost:6379/0'), # If you're on Heroku\n            'DEFAULT_TIMEOUT': 500,\n        },\n        'low': {\n            'HOST': 'localhost',\n            'PORT': 6379,\n            'DB': 0,\n        }\n    }\n\n    RQ_EXCEPTION_HANDLERS = ['path.to.my.handler'] # If you need custom exception handlers\n\n* Include ``django_rq.urls`` in your ``urls.py``:\n\n.. code-block:: python\n\n    urlpatterns += [\n        path('django-rq/', include('django_rq.urls'))\n    ]\n\n=====\nUsage\n=====\n\nPutting jobs in the queue\n-------------------------\n\n`Django-RQ` allows you to easily put jobs into any of the queues defined in\n``settings.py``. It comes with a few utility functions:\n\n* ``enqueue`` - push a job to the ``default`` queue:\n\n.. code-block:: python\n\n    import django_rq\n    django_rq.enqueue(func, foo, bar=baz)\n\n* ``get_queue`` - returns an ``Queue`` instance.\n\n.. code-block:: python\n\n    import django_rq\n    queue = django_rq.get_queue('high')\n    queue.enqueue(func, foo, bar=baz)\n\nIn addition to ``name`` argument, ``get_queue`` also accepts ``default_timeout``,\n``is_async``, ``autocommit``, ``connection`` and ``queue_class`` arguments. For example:\n\n.. code-block:: python\n\n    queue = django_rq.get_queue('default', autocommit=True, is_async=True, default_timeout=360)\n    queue.enqueue(func, foo, bar=baz)\n\nYou can provide your own singleton Redis connection object to this function so that it will not\ncreate a new connection object for each queue definition. This will help you limit\nnumber of connections to Redis server. For example:\n\n.. code-block:: python\n\n    import django_rq\n    import redis\n    redis_cursor = redis.StrictRedis(host='', port='', db='', password='')\n    high_queue = django_rq.get_queue('high', connection=redis_cursor)\n    low_queue = django_rq.get_queue('low', connection=redis_cursor)\n\n\n* ``get_connection`` - accepts a single queue name argument (defaults to \"default\")\n  and returns a connection to the queue's Redis server:\n\n.. code-block:: python\n\n    import django_rq\n    redis_conn = django_rq.get_connection('high')\n\n* ``get_worker`` - accepts optional queue names and returns a new `RQ`\n  ``Worker`` instance for specified queues (or ``default`` queue):\n\n.. code-block:: python\n\n    import django_rq\n    worker = django_rq.get_worker() # Returns a worker for \"default\" queue\n    worker.work()\n    worker = django_rq.get_worker('low', 'high') # Returns a worker for \"low\" and \"high\"\n\n\n@job decorator\n--------------\n\nTo easily turn a callable into an RQ task, you can also use the ``@job``\ndecorator that comes with ``django_rq``:\n\n.. code-block:: python\n\n    from django_rq import job\n\n    @job\n    def long_running_func():\n        pass\n    long_running_func.delay() # Enqueue function in \"default\" queue\n\n    @job('high')\n    def long_running_func():\n        pass\n    long_running_func.delay() # Enqueue function in \"high\" queue\n\nYou can pass in any arguments that RQ's job decorator accepts:\n\n.. code-block:: python\n\n    @job('default', timeout=3600)\n    def long_running_func():\n        pass\n    long_running_func.delay() # Enqueue function with a timeout of 3600 seconds.\n\nIt's possible to specify default for ``result_ttl`` decorator keyword argument\nvia ``DEFAULT_RESULT_TTL`` setting:\n\n.. code-block:: python\n\n    RQ = {\n        'DEFAULT_RESULT_TTL': 5000,\n    }\n\nWith this setting, job decorator will set ``result_ttl`` to 5000 unless it's\nspecified explicitly.\n\n\nRunning workers\n---------------\ndjango_rq provides a management command that starts a worker for every queue\nspecified as arguments::\n\n    python manage.py rqworker high default low\n\nIf you want to run ``rqworker`` in burst mode, you can pass in the ``--burst`` flag::\n\n    python manage.py rqworker high default low --burst\n\nIf you need to use custom worker, job or queue classes, it is best to use global settings\n(see `Custom queue classes`_ and `Custom job and worker classes`_). However, it is also possible\nto override such settings with command line options as follows.\n\nTo use a custom worker class, you can pass in the ``--worker-class`` flag\nwith the path to your worker::\n\n    python manage.py rqworker high default low --worker-class 'path.to.GeventWorker'\n\nTo use a custom queue class, you can pass in the ``--queue-class`` flag\nwith the path to your queue class::\n\n    python manage.py rqworker high default low --queue-class 'path.to.CustomQueue'\n\nTo use a custom job class, provide ``--job-class`` flag.\n\nStarting from version 2.10, running RQ's worker-pool is also supported::\n\n    python manage.py rqworker-pool default low medium --num-workers 4\n\nSupport for Scheduled Jobs\n--------------------------\n\nWith RQ 1.2.0. you can use `built-in scheduler \u003chttps://python-rq.org/docs/scheduling/\u003e`__\nfor your jobs. For example:\n\n.. code-block:: python\n\n    from django_rq.queues import get_queue\n    queue = get_queue('default')\n    job = queue.enqueue_at(datetime(2020, 10, 10), func)\n\nIf you are using built-in scheduler you have to start workers with scheduler support::\n\n    python manage.py rqworker --with-scheduler\n\n\nAlternatively you can use `RQ Scheduler \u003chttps://github.com/ui/rq-scheduler\u003e`__.\nAfter install you can also use the ``get_scheduler`` function to return a\n``Scheduler`` instance for queues defined in settings.py's ``RQ_QUEUES``.\nFor example:\n\n.. code-block:: python\n\n    import django_rq\n    scheduler = django_rq.get_scheduler('default')\n    job = scheduler.enqueue_at(datetime(2020, 10, 10), func)\n\nYou can also use the management command ``rqscheduler`` to start the scheduler::\n\n    python manage.py rqscheduler\n\n\nSupport for django-redis and django-redis-cache\n-----------------------------------------------\n\nIf you have `django-redis \u003chttps://django-redis.readthedocs.org/\u003e`__ or\n`django-redis-cache \u003chttps://github.com/sebleier/django-redis-cache/\u003e`__\ninstalled, you can instruct django_rq to use the same connection information\nfrom your Redis cache. This has two advantages: it's DRY and it takes advantage\nof any optimization that may be going on in your cache setup (like using\nconnection pooling or `Hiredis \u003chttps://github.com/redis/hiredis\u003e`__.)\n\nTo use configure it, use a dict with the key ``USE_REDIS_CACHE`` pointing to the\nname of the desired cache in your ``RQ_QUEUES`` dict. It goes without saying\nthat the chosen cache must exist and use the Redis backend. See your respective\nRedis cache package docs for configuration instructions. It's also important to\npoint out that since the django-redis-cache ``ShardedClient`` splits the cache\nover multiple Redis connections, it does not work.\n\nHere is an example settings fragment for `django-redis`:\n\n.. code-block:: python\n\n    CACHES = {\n        'redis-cache': {\n            'BACKEND': 'redis_cache.cache.RedisCache',\n            'LOCATION': 'localhost:6379:1',\n            'OPTIONS': {\n                'CLIENT_CLASS': 'django_redis.client.DefaultClient',\n                'MAX_ENTRIES': 5000,\n            },\n        },\n    }\n\n    RQ_QUEUES = {\n        'high': {\n            'USE_REDIS_CACHE': 'redis-cache',\n        },\n        'low': {\n            'USE_REDIS_CACHE': 'redis-cache',\n        },\n    }\n\n\nSuspending and Resuming Workers\n-------------------------------\n\nSometimes you may want to suspend RQ to prevent it from processing new jobs.\nA classic example is during the initial phase of a deployment script or in advance\nof putting your site into maintenance mode. This is particularly helpful when\nyou have jobs that are relatively long-running and might otherwise be forcibly\nkilled during the deploy.\n\nThe `suspend` command stops workers on _all_ queues (in a single Redis database)\nfrom picking up new jobs. However currently running jobs will continue until\ncompletion.\n\n.. code-block:: bash\n\n   # Suspend indefinitely\n   python manage.py rqsuspend\n\n   # Suspend for a specific duration (in seconds) then automatically\n   # resume work again.\n   python manage.py rqsuspend -d 600\n\n   # Resume work again.\n   python manage.py rqresume\n\n\nQueue Statistics\n----------------\n\n``django_rq`` also provides a dashboard to monitor the status of your queues at\n``/django-rq/`` (or whatever URL you set in your ``urls.py`` during installation.\n\nYou can also add a link to this dashboard link in ``/admin`` by adding\n``RQ_SHOW_ADMIN_LINK = True`` in ``settings.py``. Be careful though, this will\noverride the default admin template so it may interfere with other apps that\nmodifies the default admin template.\n\nThese statistics are also available in JSON format via\n``/django-rq/stats.json``, which is accessible to staff members.\nIf you need to access this view via other\nHTTP clients (for monitoring purposes), you can define ``RQ_API_TOKEN`` and access it via\n``/django-rq/stats.json/\u003cAPI_TOKEN\u003e``.\n\n.. image::  demo-django-rq-json-dashboard.png\n\nNote: Statistics of scheduled jobs display jobs from `RQ built-in scheduler \u003chttps://python-rq.org/docs/scheduling/\u003e`__,\nnot optional `RQ scheduler \u003chttps://github.com/rq/rq-scheduler\u003e`__.\n\nAdditionally, these statistics are also accessible from  the command line.\n\n.. code-block:: bash\n\n    python manage.py rqstats\n    python manage.py rqstats --interval=1  # Refreshes every second\n    python manage.py rqstats --json  # Output as JSON\n    python manage.py rqstats --yaml  # Output as YAML\n\n.. image:: demo-django-rq-cli-dashboard.gif\n\nConfiguring Sentry\n-------------------\nSentry\nshould be configured within the Django ``settings.py`` as described in the `Sentry docs \u003chttps://docs.sentry.io/platforms/python/django/\u003e`__.\n\nYou can override the default Django Sentry configuration when running the ``rqworker`` command\nby passing the ``sentry-dsn`` option:\n\n``./manage.py rqworker --sentry-dsn=https://*****@sentry.io/222222``\n\nThis will override any existing Django configuration and reinitialise Sentry,\nsetting the following Sentry options:\n\n.. code-block:: python\n\n    {\n        'debug': options.get('sentry_debug'),\n        'ca_certs': options.get('sentry_ca_certs'),\n        'integrations': [RedisIntegration(), RqIntegration(), DjangoIntegration()]\n    }\n\n\nConfiguring Logging\n-------------------\n\nRQ uses Python's ``logging``, this means you can easily configure ``rqworker``'s logging mechanism in django's\n``settings.py``. For example:\n\n.. code-block:: python\n\n    LOGGING = {\n        \"version\": 1,\n        \"disable_existing_loggers\": False,\n        \"formatters\": {\n            \"rq_console\": {\n                \"format\": \"%(asctime)s %(message)s\",\n                \"datefmt\": \"%H:%M:%S\",\n            },\n        },\n        \"handlers\": {\n            \"rq_console\": {\n                \"level\": \"DEBUG\",\n                \"class\": \"rq.logutils.ColorizingStreamHandler\",\n                \"formatter\": \"rq_console\",\n                \"exclude\": [\"%(asctime)s\"],\n            },\n        },\n        'loggers': {\n            \"rq.worker\": {\n                \"handlers\": [\"rq_console\", \"sentry\"],\n                \"level\": \"DEBUG\"\n            },\n        }\n    }\n\n\nCustom Queue Classes\n--------------------\n\nBy default, every queue will use ``DjangoRQ`` class. If you want to use a custom queue class, you can do so\nby adding a ``QUEUE_CLASS`` option on a per queue basis in ``RQ_QUEUES``:\n\n.. code-block:: python\n\n    RQ_QUEUES = {\n        'default': {\n            'HOST': 'localhost',\n            'PORT': 6379,\n            'DB': 0,\n            'QUEUE_CLASS': 'module.path.CustomClass',\n        }\n    }\n\nor you can specify ``DjangoRQ`` to use a custom class for all your queues in ``RQ`` settings:\n\n.. code-block:: python\n\n    RQ = {\n        'QUEUE_CLASS': 'module.path.CustomClass',\n    }\n\nCustom queue classes should inherit from ``django_rq.queues.DjangoRQ``.\n\nIf you are using more than one queue class (not recommended), be sure to only run workers\non queues with same queue class. For example if you have two queues defined in ``RQ_QUEUES`` and\none has custom class specified, you would have to run at least two separate workers for each\nqueue.\n\nCustom Job and Worker Classes\n-----------------------------\n\nSimilarly to custom queue classes, global custom job and worker classes can be configured using\n``JOB_CLASS`` and ``WORKER_CLASS`` settings:\n\n.. code-block:: python\n\n    RQ = {\n        'JOB_CLASS': 'module.path.CustomJobClass',\n        'WORKER_CLASS': 'module.path.CustomWorkerClass',\n    }\n\nCustom job class should inherit from ``rq.job.Job``. It will be used for all jobs\nif configured.\n\nCustom worker class should inherit from ``rq.worker.Worker``. It will be used for running\nall workers unless overridden by ``rqworker`` management command ``worker-class`` option.\n\nTesting Tip\n-----------\n\nFor an easier testing process, you can run a worker synchronously this way:\n\n.. code-block:: python\n\n    from django.test import TestCase\n    from django_rq import get_worker\n\n    class MyTest(TestCase):\n        def test_something_that_creates_jobs(self):\n            ...                      # Stuff that init jobs.\n            get_worker().work(burst=True)  # Processes all jobs then stop.\n            ...                      # Asserts that the job stuff is done.\n\nSynchronous Mode\n----------------\n\nYou can set the option ``ASYNC`` to ``False`` to make synchronous operation the\ndefault for a given queue. This will cause jobs to execute immediately and on\nthe same thread as they are dispatched, which is useful for testing and\ndebugging. For example, you might add the following after you queue\nconfiguration in your settings file:\n\n.. code-block:: python\n\n    # ... Logic to set DEBUG and TESTING settings to True or False ...\n\n    # ... Regular RQ_QUEUES setup code ...\n\n    if DEBUG or TESTING:\n        for queueConfig in RQ_QUEUES.values():\n            queueConfig['ASYNC'] = False\n\nNote that setting the ``is_async`` parameter explicitly when calling ``get_queue``\nwill override this setting.\n\n=============\nRunning Tests\n=============\n\nTo run ``django_rq``'s test suite::\n\n    `which django-admin` test django_rq --settings=django_rq.tests.settings --pythonpath=.\n\n===================\nDeploying on Ubuntu\n===================\n\nCreate an rqworker service that runs the high, default, and low queues.\n\nsudo vi /etc/systemd/system/rqworker.service\n\n.. code-block:: bash\n\n    [Unit]\n    Description=Django-RQ Worker\n    After=network.target\n\n    [Service]\n    WorkingDirectory=\u003c\u003cpath_to_your_project_folder\u003e\u003e\n    ExecStart=/home/ubuntu/.virtualenv/\u003c\u003cyour_virtualenv\u003e\u003e/bin/python \\\n        \u003c\u003cpath_to_your_project_folder\u003e\u003e/manage.py \\\n        rqworker high default low\n\n    [Install]\n    WantedBy=multi-user.target\n\nEnable and start the service\n\n.. code-block:: bash\n\n    sudo systemctl enable rqworker\n    sudo systemctl start rqworker\n\n===================\nDeploying on Heroku\n===================\n\nAdd `django-rq` to your `requirements.txt` file with:\n\n.. code-block:: bash\n\n    pip freeze \u003e requirements.txt\n\nUpdate your `Procfile` to:\n\n.. code-block:: bash\n\n    web: gunicorn --pythonpath=\"$PWD/your_app_name\" config.wsgi:application\n\n    worker: python your_app_name/manage.py rqworker high default low\n\nCommit and re-deploy. Then add your new worker with:\n\n.. code-block:: bash\n\n    heroku scale worker=1\n\n=========\nChangelog\n=========\n\nSee `CHANGELOG.md \u003chttps://github.com/rq/django-rq/blob/master/CHANGELOG.md\u003e`__.\n\n\n.. |Build Status| image:: https://github.com/rq/django-rq/actions/workflows/test.yml/badge.svg\n   :target: https://github.com/rq/django-rq/actions/workflows/test.yml\n","funding_links":["https://github.com/sponsors/selwin","https://tidelift.com/funding/github/pypi/django-rq","https://tidelift.com/subscription/pkg/pypi-django_rq?utm_source=pypi-django-rq\u0026utm_medium=referral\u0026utm_campaign=readme"],"categories":["Third-Party Packages","Python","Task Queue","HarmonyOS","Tasks","Django Utilities"],"sub_categories":["Task Queues","Windows Manager","Tools","Podcasts"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frq%2Fdjango-rq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frq%2Fdjango-rq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frq%2Fdjango-rq/lists"}