apache/beam · error · ImportError

The 'google-cloud-pubsub' library is required for…

Error message

The 'google-cloud-pubsub' library is required for TestPubsubContext. Please install it using 'pip install google-cloud-pubsub'.

What it means

TestPubsubContext depends on the optional google-cloud-pubsub package; the module imports it defensively with pubsub_v1 possibly None. If the import failed, __init__ raises ImportError telling you to pip install google-cloud-pubsub. This keeps pubsub testing helpers usable in environments that lack the dependency.

Solutions

pip install google-cloud-pubsub
Install Beam's test/gcp extras if applicable (e.g. pip install apache-beam[gcp])
Verify the import works: python -c 'import google.cloud.pubsub_v1'

Example fix

# before (ImportError at runtime)
ctx = TestPubsubContext(project_id='my-project')
// after
# $ pip install google-cloud-pubsub
ctx = TestPubsubContext(project_id='my-project')

Defensive patterns

Strategy: validation

Validate before calling

try:
    import google.cloud.pubsub_v1  # noqa
except ImportError:
    raise SystemExit("Install with: pip install google-cloud-pubsub")

Try / catch

try:
    ctx = TestPubsubContext(project_id=project)
except ImportError as e:
    _LOGGER.error('%s — install the extra and rerun', e)
    raise

Prevention

Add google-cloud-pubsub to test requirements / CI images
Use apache-beam[gcp] extras for Beam test environments
Smoke-test imports in setup scripts before running tests

When it happens

Trigger: Instantiating TestPubsubContext in an environment where google-cloud-pubsub is not installed (or an incompatible installed version broke the import).

Common situations: Running Beam tests in a slim venv or CI image without extra pubsub extras; dependency removed during environment rebuild; version conflict hiding the package.

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

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

Appendix: source

Thrown at sdks/python/apache_beam/testing/pubsub_test_context.py:47

# pylint: enable=wrong-import-order, wrong-import-position


class TestPubsubContext:
  """A highly advanced Pub/Sub resource lifecycle manager for Python integration tests.
    Implements cascading third-party subscription cleanup and selective
    graceful teardown for debugging on failures.

    Includes a safety 'dry_run' switch for safe deployment and validation of resources.
    Any catastrophic leaks are handled independently by the global 'stale_cleaner.py'.
    """
  def __init__(
      self,
      project_id,
      dry_run=False
  ):  # Keep dry_run=False to allow actual deletions during testing

    if pubsub_v1 is None:
      raise ImportError(
          "The 'google-cloud-pubsub' library is required for TestPubsubContext. "
          "Please install it using 'pip install google-cloud-pubsub'.")

    self.project_id = project_id
    self.dry_run = dry_run
    self.publisher = pubsub_v1.PublisherClient()
    self.subscriber = pubsub_v1.SubscriberClient()

    # Lists to track resources created during the test execution
    self.tracked_topics = []
    self.tracked_subscriptions = []
    self.caller_class = "UnknownTestClass"
    stack = inspect.stack()

    for frame in stack:
      self_obj = frame[0].f_locals.get('self', None)
      if self_obj and hasattr(self_obj, '__class__'):
        self.caller_class = self_obj.__class__.__name__

View on GitHub (pinned to 12126d8942)