Registry /
gcp / apache-airflow-providers-google
Install & Compatibility
Where this runs
tested against v22.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 96.9s
py 3.11
✕ build_error
✓ 101.4s
py 3.12
✕ build_error
✓ 88.3s
py 3.13
✕ build_error
✓ 84.8s
py 3.9
✕ build_error
✕ timeout
2022MB installed
● package 2022MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BigQueryInsertJobOperator
✓ from airflow.providers.google.cloud.operators.bigquery import BigQueryInsertJobOperator
GCSUploadSessionCompleteSensor
✓ from airflow.providers.google.cloud.sensors.gcs import GCSUploadSessionCompleteSensor
CloudStorageHook
✓ from airflow.providers.google.cloud.hooks.gcs import GCSHook
GoogleBaseHook
✓ from airflow.providers.google.common.hooks.base_google import GoogleBaseHook
This quickstart demonstrates a simple Airflow DAG using the `BigQueryInsertJobOperator` from the Google Cloud Provider. It assumes a 'google_cloud_default' Airflow connection is configured, typically leveraging Application Default Credentials (ADC) or a service account key file. Ensure the `GCP_PROJECT_ID` environment variable is set or replace 'your-gcp-project-id' with your actual GCP project ID, and similarly for dataset and table IDs.
import os
from datetime import datetime
from airflow.models.dag import DAG
from airflow.providers.google.cloud.operators.bigquery import BigQueryInsertJobOperator
# Ensure you have a 'google_cloud_default' connection configured in Airflow.
# This connection typically uses Application Default Credentials (ADC).
# For local testing, ensure GOOGLE_APPLICATION_CREDENTIALS points to a service account key.
with DAG(
dag_id='gcp_bigquery_quickstart',
start_date=datetime(2023, 1, 1),
schedule_interval=None,
catchup=False,
tags=['gcp', 'bigquery', 'example'],
) as dag:
insert_job = BigQueryInsertJobOperator(
task_id='insert_row_to_bigquery',
project_id=os.environ.get('GCP_PROJECT_ID', 'your-gcp-project-id'),
configuration={
'query': {
'query': 'INSERT INTO `dataset.table` (column1, column2) VALUES ("value1", "value2")',
'useLegacySql': False,
'destinationTable': {
'projectId': os.environ.get('GCP_PROJECT_ID', 'your-gcp-project-id'),
'datasetId': 'your_dataset_id',
'tableId': 'your_table_id'
}
}
},
gcp_conn_id='google_cloud_default',
)
Debug
Known issues
breakingEach version of `apache-airflow-providers-google` has a minimum required Apache Airflow core version. For example, provider version 21.0.0 requires `apache-airflow>=2.11.0`. Installing a provider version incompatible with your Airflow core can lead to unexpected behavior or dependency conflicts.fixAlways check the `apache-airflow-providers-google` documentation (or PyPI page) for the `apache-airflow` core version requirement for your specific provider version. Upgrade `apache-airflow` if necessary before upgrading the provider.
affects: All versions
breakingFrequent updates to the underlying `google-ads` client library (e.g., v5 to v8, v12 to v13) and changes in object types (from native protobuf to proto-plus) have historically caused breaking changes and dependency conflicts, especially when other Google client libraries are also used in the same environment. This can lead to `VersionConflict` errors.fixPin specific versions of `apache-airflow-providers-google` and `google-ads` to known compatible combinations. If encountering `VersionConflict` with `proto-plus`, explicitly constrain its version, though this may require downgrading other `google-cloud-xxx` libraries. Test thoroughly after any updates involving `google-ads`.
affects: Versions 5.0.0+, 10.1.0+, 17.0.0+, 19.0.0+, 21.0.0+
breakingThe `delegate_to` parameter for service account impersonation has been deprecated and removed in favor of `impersonation_chain`. Using `delegate_to` in newer provider versions will cause errors.fixReplace `delegate_to='service-account-email'` with `impersonation_chain=['service-account-email']` in operators, hooks, and triggers where service account impersonation is used.
affects: Provider versions that removed `delegate_to` (e.g., around v10.0.0+)
breakingOperators related to Google Cloud Data Catalog have been renamed and/or moved to the Dataplex provider. For example, `CloudDataCatalogCreateEntryOperator` has been replaced by `DataplexCatalogCreateEntryOperator`.fixUpdate import paths and operator names to use the `dataplex` module for Data Catalog functionalities. Refer to the provider's changelog for specific operator renames.
affects: Versions 19.0.0+
gotchaAuthentication to Google Cloud relies on Airflow connections. The default `google_cloud_default` connection typically uses Application Default Credentials (ADC). Misconfiguration of ADC (e.g., `GOOGLE_APPLICATION_CREDENTIALS` not set, or incorrect service account key in Airflow connection) is a common source of authorization errors.fixEnsure your Airflow environment has the `google_cloud_default` connection properly configured. If using a service account key, provide it via 'Keyfile Path' or 'Keyfile JSON' in the connection details. For ADC, ensure the environment where Airflow workers run has appropriate credentials (e.g., `GOOGLE_APPLICATION_CREDENTIALS` environment variable set, or running on GCP infrastructure like GCE/GKE).
affects: All versions
gotchaHistorically, conflicts between `apache-airflow-providers-google` and `apache-airflow-providers-apache-beam` have arisen due to differing dependencies on `google-cloud-bigquery` client versions, especially when using `apache-beam[gcp]` extra. This can lead to unexpected behavior in BigQuery operators.fixRefer to the provider's documentation on cross-provider dependencies and extras. If installing both, use the recommended `pip install apache-airflow-providers-google[apache.beam]` (or similar) to ensure compatible dependencies are installed.
affects: Provider versions before 3.0.0 (where specific integration changes were made). Still a potential for new conflicts with future `apache-beam` updates.
gotchaInstalling certain Python packages with compiled extensions (e.g., `scikit-learn`, `numpy`, `pandas`) can fail in minimal environments like `alpine` if build tools (like `gcc` and Python development headers) are not installed. The error `ERROR: Unknown compiler(s)` or similar during metadata preparation indicates missing compilers.fixEnsure that build tools and Python development headers are installed in your environment before attempting to install packages with C extensions. For `alpine` distributions, this typically involves running `apk add --no-cache build-base python3-dev` in your Dockerfile or environment setup.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'airflow.providers'
This error occurs when the 'apache-airflow-providers-google' package is not installed or not recognized by Airflow.
fixEnsure that the 'apache-airflow-providers-google' package is installed and recognized by Airflow. You can install it using pip: 'pip install apache-airflow-providers-google'.
ImportError: cannot import name 'BigQueryOperator' from 'airflow.providers.google.cloud.operators.bigquery'
This error occurs when the 'BigQueryOperator' cannot be imported due to missing or incompatible versions of the 'apache-airflow-providers-google' package.
fixEnsure that the 'apache-airflow-providers-google' package is installed and up to date. You can install or upgrade it using pip: 'pip install --upgrade apache-airflow-providers-google'.
ImportError: cannot import name 'SUPERVISOR_COMMS' from 'airflow.sdk.execution_time.task_runner'
This error occurs due to an issue with the 'dag.test()' function in Airflow, leading to an import error.
fixThis issue has been reported in the Airflow GitHub repository. It's recommended to check for updates or patches that address this problem.
ImportError: cannot import name 'DAG' from 'airflow' (unknown location)
This error occurs when the 'DAG' class cannot be imported from the 'airflow' module, possibly due to installation issues or incorrect file naming.
fixEnsure that Airflow is installed correctly and that there are no files named 'airflow.py' in your project directory that could cause import conflicts.
ImportError: cannot import name '_check_google_client_version' from 'pandas_gbq.gbq'
This error occurs when the 'bigquery_hook' in Airflow tries to import '_check_google_client_version' from 'pandas_gbq', but the function has been removed in newer versions of 'pandas_gbq'.
fixDowngrade 'pandas_gbq' to a version that includes '_check_google_client_version', such as version 0.14.1, to maintain compatibility with Airflow 1.10.9.
Upgrade
Version history
22.4.0latest on PyPI · released Aug 23, 2026
Audit
Dependencies
apache-airflowrequiredCore Airflow dependency; provider requires >=2.11.0
google-cloud-bigqueryoptionalRequired for BigQuery operations, specific version varies with provider
google-cloud-storageoptionalRequired for Google Cloud Storage operations, specific version varies with provider
google-adsoptionalRequired for Google Ads operations, specific version varies with provider