apache/beam · error · ImportError

Failed to import redis. You can ensure it is installed by in

Error message

Failed to import redis. You can ensure it is installed by installing the redis beam extra

What it means

RedisCache.__init__ checks whether the `redis` Python package was importable; if not, it raises ImportError telling the user to install the redis extra for Beam. Redis-backed caching cannot be constructed without the dependency.

Source

Thrown at sdks/python/apache_beam/io/requestresponse.py:695

      time_to_live: `(Union[int, timedelta])` The time-to-live (TTL) for
        records stored in Redis. Provide an integer (in seconds) or a
        `datetime.timedelta` object.
      request_coder: (Optional[`coders.Coder`]) coder for encoding requests.
      response_coder: (Optional[`coders.Coder`]) coder for decoding responses
        received from Redis.
      kwargs: Optional additional keyword arguments that
        are required to connect to your redis server. Same as `redis.Redis()`.
    """
    self._host = host
    self._port = port
    self._time_to_live = time_to_live
    self._request_coder = request_coder
    self._response_coder = response_coder
    self._kwargs = kwargs if kwargs else {}
    self._source_caller = None

    if redis is None:
      raise ImportError(
          'Failed to import redis. You can ensure it is '
          'installed by installing the redis beam extra')

  def get_read(self):
    """get_read returns a PTransform for reading from the cache."""
    ensure_coders_exist(self._request_coder)
    return _ReadFromRedis(
        self._host,
        self._port,
        time_to_live=self._time_to_live,
        kwargs=self._kwargs,
        request_coder=self._request_coder,
        response_coder=self._response_coder,
        source_caller=self._source_caller)

  def get_write(self):
    """returns a PTransform for writing to the cache."""
    ensure_coders_exist(self._request_coder)

View on GitHub (pinned to 12126d8942)

Solutions

Install the dependency: pip install apache-beam[redis] (or pip install redis).
Add 'redis' (or apache-beam[redis]) to your requirements_file/setup.py so workers also install it.
Verify the import works in the same environment the pipeline executes in (workers, containers), not just locally.
If Redis is unavailable, switch to a different Cache implementation that does not need redis.

Example fix

# before
pip install apache-beam
# after
pip install 'apache-beam[redis]'

Defensive patterns

Strategy: validation

Validate before calling

try:
  import redis
except ImportError:
  raise ImportError("install with: pip install 'apache-beam[redis]'")

Try / catch

try:
  cache = RedisCache(client, prefix, request_coder=rc)
except ImportError:
  cache = None  # run without caching or fail fast in setup

Prevention

Install apache-beam[redis] in every environment the pipeline runs in (driver and workers)
Pin the redis package in requirements/setup.py
Smoke-test imports in worker containers before deploying

When it happens

Trigger: Instantiating RedisCache (or using Cache with redis backend) in an environment where `import redis` failed — the package is not installed in the worker/driver environment.

Common situations: Running Beam pipelines on Dataflow/runners where the redis package was not added to requirements; dev machine missing the extra; dependency conflicts where redis failed to import.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/20d93646bbd4b6a8. Report an issue: GitHub.