apache/beam · error · ImportError

google-cloud-bigquery-storage is required for ReadBigQueryCh

Error message

google-cloud-bigquery-storage is required for ReadBigQueryChangeHistory. Install it with: pip install google-cloud-bigquery-storage

What it means

ReadBigQueryChangeHistory depends on the google-cloud-bigquery-storage package to read rows via the BigQuery Storage Read API. The module-level import failed (package not installed), so __init__ raises ImportError with the exact pip install command. The transform cannot function without this dependency.

Source

Thrown at sdks/python/apache_beam/io/gcp/bigquery_change_history.py:1205

      table: str,
      poll_interval_sec: float = 60,
      start_time: Optional[float] = None,
      stop_time: Optional[float] = None,
      change_function: str = 'APPENDS',
      buffer_sec: float = 10,
      project: Optional[str] = None,
      temp_dataset: Optional[str] = None,
      location: Optional[str] = None,
      change_type_column: str = 'change_type',
      change_timestamp_column: str = 'change_timestamp',
      columns: Optional[list[str]] = None,
      row_filter: Optional[str] = None,
      batch_arrow_read: bool = True,
      max_split_rounds: int = 1,
      reshuffle_decompress: bool = True) -> None:
    super().__init__()
    if bq_storage is None:
      raise ImportError(
          'google-cloud-bigquery-storage is required for '
          'ReadBigQueryChangeHistory. Install it with: '
          'pip install google-cloud-bigquery-storage')
    if pyarrow is None:
      raise ImportError(
          'pyarrow is required for ReadBigQueryChangeHistory. '
          'Install it with: pip install pyarrow')
    if change_function not in ('CHANGES', 'APPENDS'):
      raise ValueError(
          f"change_function must be 'CHANGES' or 'APPENDS', "
          f"got '{change_function}'")
    if poll_interval_sec < 15:
      raise ValueError(
          f'poll_interval_sec must be >= 15, got {poll_interval_sec}')
    if buffer_sec < 0:
      raise ValueError(f'buffer_sec must be >= 0, got {buffer_sec}')
    self._table = table
    self._poll_interval_sec = poll_interval_sec

View on GitHub (pinned to 12126d8942)

Solutions

1. Run: pip install google-cloud-bigquery-storage
2. Install the full GCP extras: pip install 'apache-beam[gcp]'
3. If deploying to Dataflow, add the package to setup.py install_requires / requirements.txt so it is staged with the job.

Example fix

// before
pip install apache-beam
// after
pip install 'apache-beam[gcp]'

try:
    import google.cloud.bigquery_storage as bq_storage
except ImportError:
    raise SystemExit("pip install 'apache-beam[gcp]' or pip install google-cloud-bigquery-storage")

try:
    transform = ReadFromBigQueryChangeHistory(...)
except ImportError as e:
    log.error("install missing dependency: %s", e)

When it happens

Trigger: Constructing ReadFromBigQueryChangeHistory(...) in an environment where google-cloud-bigquery-storage is not installed (the module-level 'bq_storage' import is None), e.g. a minimal Beam install without GCP extras.

Common situations: Deploying to runners (Dataflow, Flink) where extra dependencies were not bundled; local venv created with 'pip install apache-beam' without the 'gcp' extra; dependency resolution removed the package in a constrained environment.

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

• pyarrow is required for ReadBigQueryChangeHistory. Install i
• Could not import joblib in this execution environment. For h
• Please specify a BigQuery table to read from.
• Encountered unsupported parameter(s) in read_gbq: {kwargs.ke
• {module} was not imported correctly, have you used an `impor

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