Install & Compatibility
Where this runs
tested against v4.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.468s · 73MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.436s · 74MB
73MB installed
● package 73MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RedisChannelLayer
✓ from channels_redis.core import RedisChannelLayer
✗ from channels.layers import RedisChannelLayer
While older tutorials or Channels 1.x might imply a direct import from channels.layers, the correct and current import path for the Redis-backed layer is from channels_redis.core.
RedisPubSubChannelLayer
✓ from channels_redis.pubsub import RedisPubSubChannelLayer
This is a newer, beta-status layer that leverages Redis Pub/Sub for message dispatch.
To use channels-redis, you typically configure your `CHANNEL_LAYERS` setting in `settings.py` and set up your ASGI application in `asgi.py`. Ensure a Redis server (version 5.0 or higher) is running. This example shows a basic setup for the default `RedisChannelLayer` and a structure for `asgi.py`. You would further define `websocket_urlpatterns` in your app's `routing.py` and include it in the `URLRouter`.
import os
from django.core.asgi import get_asgi_application
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
from django.conf import settings
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "your_project.settings")
# In your settings.py (e.g., your_project/settings.py):
# CHANNEL_LAYERS = {
# "default": {
# "BACKEND": "channels_redis.core.RedisChannelLayer",
# "CONFIG": {
# "hosts": [os.environ.get('REDIS_URL', 'redis://localhost:6379')],
# },
# },
# }
# Example routing (your_project/routing.py)
# from django.urls import re_path
# from chat.consumers import ChatConsumer
# websocket_urlpatterns = [
# re_path(r'ws/chat/(?P<room_name>\w+)/$', ChatConsumer.as_asgi()),
# ]
application = ProtocolTypeRouter({
"http": get_asgi_application(),
"websocket": AuthMiddlewareStack(
URLRouter(
# Replace with your app's websocket_urlpatterns
# Example: chat.routing.websocket_urlpatterns
[] # Placeholder for actual URLRouter patterns
)
),
})
Debug
Known issues
breakingVersion 4.0.0 migrated from `aioredis` to `redis-py`. This changed the configuration for `hosts`; specifying hosts as tuples is no longer supported, and for dicts, only the `address` key is considered. Pass `password` inline in the URI.fixUpdate `CHANNEL_LAYERS['default']['CONFIG']['hosts']` to use URI strings (e.g., 'redis://localhost:6379') or dicts with an 'address' key. Ensure `redis-py` is at least 4.5.3.
affects: 4.0.0+
deprecatedThe `asgi_redis` package is an older name for channels-redis and is intended for Channels 1.x projects. Do not use it for Channels 2.x+ projects.fixFor Channels 2.x and newer, install and use `channels-redis` instead of `asgi_redis`.
affects: <2.0.0
gotchaThe `RedisPubSubChannelLayer` is currently in Beta status. This means it may be subject to breaking changes as it matures. Use with caution in production environments where stability is paramount.
breakingChannels-redis 4.x dropped support for older Python and Django versions. Python 3.8 support was dropped in 4.3.0, and Python 3.7 was dropped in 4.2.0. Minimum Django version is 4.2.2 for `channels-redis` 4.3.0.fixEnsure your project uses Python 3.9+ and Django 4.2.2+ to be compatible with channels-redis 4.3.0. Refer to specific changelogs for minimum version requirements for other 4.x releases.
affects: 4.x
gotchaWhen using `async_to_sync()` with `redis-py 4.x`, ensure that Redis connections are manually closed when an event loop shuts down to avoid warnings or resource leaks. This was addressed for the pub-sub layer in 4.1.0 but remains a general consideration.fixImplement explicit connection closing mechanisms where `async_to_sync` is used, especially if managing custom connection pools or unusual application lifecycles.
affects: 4.0.0+
gotchaWhen using sharding, passing multiple hosts to `CONFIG['hosts']` enables sharding. However, changing this host list can lead to loss of some sharded data. All servers talking to the same layer should have the same prefix and host list.fixPlan your Redis sharding configuration carefully and avoid frequent changes to the `hosts` list in production. Ensure consistent configuration across all application instances.
affects: All versions with sharding
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'channels-redis'
The `channels-redis` package is not installed in the active Python environment or is misspelled in the import statement.
fixEnsure `channels-redis` is installed: `pip install channels-redis`
ConnectionRefusedError: [Errno 61] Connection refused
The Django Channels application is unable to connect to the Redis server. This usually means the Redis server is not running, is not accessible at the specified host/port, or a firewall is blocking the connection.
fixStart the Redis server (e.g., `redis-server` command), verify the host and port in `CHANNEL_LAYERS` settings, and ensure no firewall is blocking port 6379 (or your configured Redis port).
channels.exceptions.InvalidChannelLayerError: Cannot import BACKEND 'channels_redis.core.RedisChannelLayer' specified for default
The `BACKEND` path specified in your `CHANNEL_LAYERS` setting in `settings.py` is incorrect, or the `channels_redis` package is not correctly installed or cannot be found by Django.
fixDouble-check the `CHANNEL_LAYERS` configuration in `settings.py` to ensure the `BACKEND` path is exactly `channels_redis.core.RedisChannelLayer`. Verify `channels-redis` is installed and accessible in your Python environment.
AttributeError: 'Redis' object has no attribute 'bzpopmin'
This error typically occurs when the Redis server version is older than 5.0, which is required for the `BZPOPMIN` command used by `channels-redis`.
fixUpgrade your Redis server to version 5.0 or newer. Alternatively, if using `RedisChannelLayer`, consider switching to `RedisPubSubChannelLayer` if your use case permits, as it uses different commands and is in Beta.
Upgrade
Version history
4.3.0latest on PyPI · released Jul 22, 2025
Audit
Dependencies
redisrequiredRequired for Redis server interaction. Minimum version 4.6.0. Redis server >= 5.0 is also a prerequisite.
channelsrequiredThe core Django Channels library, which channels-redis extends. Minimum version 4.2.0.
msgpackrequiredUsed for message serialization. Version ~1.0.
asgirefrequiredBase ASGI library. Version <4, >=3.9.
hiredisoptionalOptional dependency to improve layer performance, used automatically if installed.