apache/beam · error · ImportError

Interactive runner not available, please install apache_beam

Error message

Interactive runner not available, please install apache_beam[interactive]

What it means

apache_beam.runners.create_runner() resolves a runner by name and imports its module. When the import fails with ImportError and the requested name contains 'interactive', it re-raises with this message telling the user to install the interactive extras. The interactive runner is not shipped with the base apache_beam package.

Source

Thrown at sdks/python/apache_beam/runners/runner.py:91

  # Get the qualified runner name by using the lower case runner name. If that
  # fails try appending the name with 'runner' and check if it matches.
  # If that also fails, use the given runner name as is.
  runner_name = _RUNNER_MAP.get(
      runner_name.lower(),
      _RUNNER_MAP.get(runner_name.lower() + 'runner', runner_name))

  if '.' in runner_name:
    module, runner = runner_name.rsplit('.', 1)
    try:
      return getattr(importlib.import_module(module), runner)()
    except ImportError:
      if 'dataflow' in runner_name.lower():
        raise ImportError(
            'Google Cloud Dataflow runner not available, '
            'please install apache_beam[gcp]')
      elif 'interactive' in runner_name.lower():
        raise ImportError(
            'Interactive runner not available, '
            'please install apache_beam[interactive]')
      else:
        raise
  else:
    raise ValueError(
        'Unexpected pipeline runner: %s. Valid values are %s '
        'or the fully qualified name of a PipelineRunner subclass.' %
        (runner_name, ', '.join(StandardOptions.KNOWN_RUNNER_NAMES)))


class PipelineRunner(object):
  """A runner of a pipeline object.

  The base runner provides a run() method for visiting every node in the
  pipeline's DAG and executing the transforms computing the PValue in the node.

  A custom runner will typically provide implementations for some of the

View on GitHub (pinned to 12126d8942)

Solutions

1. Install the extras: pip install 'apache_beam[interactive]'
2. If you meant a different runner, pass a valid runner name or a PipelineRunner subclass per StandardOptions.KNOWN_RUNNER_NAMES
3. Verify the installed apache_beam version supports the interactive runner

Example fix

// before
runner = create_runner('InteractiveRunner')
// after
# pip install 'apache_beam[interactive]'
runner = create_runner('InteractiveRunner')

try:
    import apache_beam.runners.interactive
    HAS_INTERACTIVE = True
except ImportError:
    HAS_INTERACTIVE = False

try:
    runner = create_runner('InteractiveRunner')
except ImportError as e:
    if 'interactive' in str(e).lower():
        runner = create_runner('DirectRunner')  # fallback
    else:
        raise

When it happens

Trigger: Calling create_runner('InteractiveRunner') (or any name containing 'interactive', case-insensitive) without apache_beam[interactive] installed, so the deferred import of the interactive runner module raises ImportError.

Common situations: Running pipelines with beam interactive (notebook) workflows in a slim environment; CI containers installed only apache_beam without extras; a typo'd or misspelled runner name accidentally containing 'interactive'.

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

• This pipeline contains a DillCoder which requires the dill p
• Module {parts[0]} not found in sys.modules
• Azure dependencies are not installed. Unable to run.
• Failed to import hdfs. You can ensure it is installed by ins
• Failed to import redis. You can ensure it is installed by in

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