agentscope-ai/agentscope · error · ImportError

The 'redis' package is required for RedisMessageBus. Install

Error message

The 'redis' package is required for RedisMessageBus. Install it with: pip install redis[async]

What it means

RedisMessageBus.__aenter__ raises ImportError when the optional 'redis' Python package (with asyncio support) is not installed in the environment. The library treats redis as an optional dependency and only imports it lazily when the bus is actually entered, so construction succeeds but 'async with bus' fails.

Source

Thrown at src/agentscope/app/message_bus/_redis_message_bus.py:105

        self._owned_pool: ConnectionPool | None = None

    async def __aenter__(self) -> Self:
        """Create the connection pool and Redis client.

        If an external pool was supplied at construction time it is
        used directly and its lifecycle remains the caller's
        responsibility. Otherwise, an internal pool is created from the
        stored host/port/db parameters and will be closed by
        :meth:`aclose`.

        Returns:
            `Self`:
                The bus, ready for use as an async context manager.
        """
        try:
            import redis.asyncio as aioredis
        except ImportError as e:
            raise ImportError(
                "The 'redis' package is required for RedisMessageBus. "
                "Install it with: pip install redis[async]",
            ) from e

        if self._external_pool is not None:
            pool = self._external_pool
        else:
            self._owned_pool = aioredis.ConnectionPool(
                host=self._host,
                port=self._port,
                db=self._db,
                password=self._password,
                decode_responses=True,
                **self._kwargs,
            )
            pool = self._owned_pool

        self._client = aioredis.Redis(connection_pool=pool)

View on GitHub (pinned to e90f1c7592)

Solutions

1. Install the async-capable redis client: pip install 'redis[async]'
2. Add 'redis[async]' to your project's dependencies/lockfile so it survives rebuilds
3. If it was working before, check that a requirements pruning or version downgrade did not remove redis.asyncio
4. Verify with: python -c "import redis.asyncio"

Example fix

# before
bus = RedisMessageBus(url="redis://localhost:6379")
async with bus: ...
# ImportError: The 'redis' package is required...

# after
# shell:
pip install 'redis[async]'

def redis_available() -> bool:
    try:
        import redis.asyncio  # noqa: F401
        return True
    except ImportError:
        return False

assert redis_available(), "pip install 'redis[async]'"

null

try:
    async with RedisMessageBus(url=url) as bus:
        ...
except ImportError as e:
    if 'redis' in str(e):
        raise RuntimeError('Install redis[async] to use RedisMessageBus') from e
    raise

When it happens

Trigger: Creating a RedisMessageBus and entering it: 'async with RedisMessageBus(...) as bus:' in an environment where 'import redis.asyncio' raises ImportError (package missing, or an ancient redis version without the asyncio subpackage).

Common situations: Installing agentscope without the message-bus extra; a fresh venv/CI image; a requirements pin of an old redis version (<4.2) that lacks redis.asyncio; dependency pruning tools stripping 'unused' imports.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• S3BlobStore requires the optional dependency ``aioboto3``. I
• Please install pandas to use the Excel parser. You can insta
• Please install pypdf to use the PDF parser. You can install
• Please install python-pptx to use the PowerPoint parser. You

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/d3ad5c0eaa0d88c5. Report an issue: GitHub.