Celery in a Django project does not connect to Redis or ignores the broker URL
ModuleNotFoundError: No module named 'redis'Short answer
Celery talks to Redis through a client library and reads its broker URL from your Django settings. It fails when the redis extra is not installed, when the setting is not prefixed to match the namespace, when the URL points at the wrong host, or when Redis evicts Celery's keys. Check each in that order.
Fix it fast
1Find out which cause you have
Ask Celery which broker it is really using. The first lines of the worker output show the transport and URL.
celery -A proj worker -l INFO2Match what you see, then jump to its fix
- 1
ModuleNotFoundError: No module named 'redis'Celery was installed without the Redis supportFix - 2
The worker banner shows an amqp:// transport instead of redis://The settings are not read, so Celery falls back to its default brokerFix - 3
Connection errors from the worker while the redis CLI works from another shell or containerThe URL points at the wrong placeFix - 4
InconsistencyError mentioning _kombu.binding.celeryRedis is evicting Celery's keysFix
- 1
What does the error look like?
ModuleNotFoundError: No module named 'redis'kombu.exceptions.InconsistencyError: ... _kombu.binding.celeryThe worker banner shows an amqp:// transport, Celery's default, instead of your Redis URL
Cause 1 of 4
Celery was installed without the Redis support
1Check
Redis support comes from the redis extra. Plain celery does not install the Redis client.
pip show redis2Fix
Install Celery with the extra.
pip install -U "celery[redis]"3Verify
The import now works in the same environment as the worker.
python -c "import redis; print(redis.__version__)"Confirmed by docs.celeryq.dev
Cause 2 of 4
The settings are not read, so Celery falls back to its default broker
1Check
With config_from_object('django.conf:settings', namespace='CELERY'), every Celery option must be upper case and start with CELERY_. So broker_url becomes CELERY_BROKER_URL; a plain BROKER_URL in settings.py is ignored. Also check that proj/__init__.py imports the app.
grep -n -E "CELERY_|config_from_object" proj/settings.py proj/celery.py2Fix
Use the namespaced name, and import the app in the package's __init__.py so it loads when Django starts.
# proj/settings.py
CELERY_BROKER_URL = "redis://localhost:6379/0"
# proj/__init__.py
from .celery import app as celery_app
__all__ = ("celery_app",)3Verify
Start the worker from the project root and read the banner.
celery -A proj worker -l INFOConfirmed by docs.celeryq.dev
Cause 3 of 4
The URL points at the wrong place
1Check
The URL form is redis://:password@hostname:port/db_number. Missing parts default to localhost, port 6379 and database 0, which is wrong in a container or a managed Redis.
redis-cli -u redis://HOST:6379/0 ping2Fix
Write the full URL, with the password if one is set, and use the service name in Docker.
CELERY_BROKER_URL = "redis://:mypassword@redis:6379/0"3Verify
Restart the worker and send a task.
python manage.py shell -c "from proj.tasks import add; print(add.delay(2, 3).id)"Confirmed by docs.celeryq.dev
Cause 4 of 4
Redis is evicting Celery's keys
1Check
Celery's docs say this can happen when Redis evicts keys under memory pressure. Look at the policy.
redis-cli CONFIG GET maxmemory-policy2Fix
Set maxmemory and a maxmemory-policy of noeviction or allkeys-lru for the Redis instance used as a broker.
redis-cli CONFIG SET maxmemory-policy noeviction3Verify
Read the setting back.
redis-cli CONFIG GET maxmemory-policyConfirmed by docs.celeryq.dev
How do I stop it coming back?
- Give Celery its own Redis database or instance, with a policy that does not evict its keys.
- Print the broker URL (without the password) in your startup log.
- Keep the broker URL in an environment variable so containers and laptops differ only by config.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
Related fixes
Back end
Airflow SSHOperator stops a long script with SSH command timed out
airflow.exceptions.AirflowException: SSH command timed out
SSHOperator waits only 10 seconds for a command by default.
3 causes, each with a fixBack end
Python asyncio: Task was destroyed but it is pending
RuntimeWarning: coroutine '...' was never awaited
A task was still unfinished when Python threw it away.
4 causes, each with a fixBack end
Django form POST returns 403 Forbidden: CSRF verification failed
CSRF verification failed. Request aborted.
Django rejects an unsafe request when the CSRF cookie or the form token is missing or wrong, or when the Origin or Referer check fails.
5 causes, each with a fixBack end
Django cannot import corsheaders (django-cors-headers)
ImportError: No module named corsheaders
The pip package is django-cors-headers, but the module Django imports is corsheaders.
3 causes, each with a fixBack end
Django raises NoReverseMatch when building a URL
NoReverseMatch
NoReverseMatch means Django looked for a named URL pattern that fits the name and arguments you gave and found none.
4 causes, each with a fixBack end
npm install fails inside a node:alpine Docker build
Docker Node Alpine Image Build Fails on node-gyp
The node alpine images ship almost nothing beyond Node.js, so a native module that node-gyp must compile has no Python, make or C++ compiler.
2 causes, each with a fix