Install & Compatibility
Where this runs
tested against v0.29.20 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 6.246s · 595.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 25.0s · import 5.464s · 553MB
587MB installed
● package 587MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BigQueryResource
✓ from dagster_gcp import BigQueryResource
BigQueryIOManager
✓ from dagster_gcp import BigQueryIOManager
GCSResource
✓ from dagster_gcp.gcs import GCSResource
GCSPickleIOManager
✓ from dagster_gcp.gcs import GCSPickleIOManager
DataprocResource
✓ from dagster_gcp.dataproc import DataprocResource
PipesDataprocJobClient
✓ from dagster_gcp.pipes import PipesDataprocJobClient
This API is currently in preview and may have breaking changes in patch releases; not recommended for production.
This quickstart demonstrates defining a Dagster asset that interacts with Google BigQuery using `BigQueryResource`. It shows how to configure the resource and execute a simple SQL query. Authentication is expected via standard GCP mechanisms (like `GOOGLE_APPLICATION_CREDENTIALS` environment variable) or configured directly on the resource via `gcp_credentials`.
import os
from dagster import Definitions, asset, EnvVar
from dagster_gcp import BigQueryResource
# Ensure GOOGLE_APPLICATION_CREDENTIALS or similar env var is set for local execution
# For simplicity, project is hardcoded or read from an env var. In production, consider more robust auth.
@asset
def my_bq_table(bigquery: BigQueryResource):
"""An asset that queries a BigQuery table."""
project_id = os.environ.get('GCP_PROJECT_ID', 'your-gcp-project')
dataset_id = os.environ.get('BIGQUERY_DATASET', 'my_dataset')
table_id = os.environ.get('BIGQUERY_TABLE', 'my_table')
# Example: Execute a simple query
query = f"SELECT COUNT(*) FROM `{project_id}.{dataset_id}.{table_id}`"
with bigquery.get_client() as client:
query_job = client.query(query)
results = query_job.result()
print(f"Query executed successfully. First row: {list(results)[0]}")
defs = Definitions(
assets=[my_bq_table],
resources={
"bigquery": BigQueryResource(
project=EnvVar("GCP_PROJECT_ID"), # Use EnvVar for production
location=EnvVar("GCP_REGION", default_value="us-central1"),
# You can also pass gcp_credentials as a base64 encoded JSON string via EnvVar
)
},
)
# To run this locally:
# 1. Set environment variables, e.g., GOOGLE_APPLICATION_CREDENTIALS, GCP_PROJECT_ID, BIGQUERY_DATASET, BIGQUERY_TABLE
# 2. Run `dagster dev -f your_file.py`
# 3. Navigate to Dagit UI, find 'my_bq_table' asset and materialize it.
Debug
Known issues
gotchaDagster integration libraries, including `dagster-gcp`, follow a pre-1.0 versioning track (e.g., `0.x.y`) even though Dagster core is at `1.x.y`. While `0.16+` library releases are generally compatible with `Dagster 1.x`, their APIs are not as mature as core and 'Beta APIs may have breaking changes in minor version releases, with behavior changes in patch releases'.fixRefer to the specific library's changelog for each upgrade. Test integrations thoroughly after updates, especially for 'beta' or 'preview' features.
affects: All 0.x.y versions of `dagster-gcp`.
gotchaProper GCP authentication is critical. `dagster-gcp` components rely on standard Google Cloud authentication mechanisms. Misconfiguration of `GOOGLE_APPLICATION_CREDENTIALS` environment variable or incorrect `gcp_credentials` in resource configuration is a common issue.fixEnsure `GOOGLE_APPLICATION_CREDENTIALS` points to a valid service account key file, or configure `gcp_credentials` on the resource with a base64 encoded service account JSON string. Verify the service account has necessary permissions for the GCP services being accessed.
affects: All versions
gotchaWhen using `BigQueryIOManager` for assets or ops, if a dataset is not explicitly specified via `project` and `dataset` configuration, `key_prefix` on assets, or `schema` in op output metadata, it will default to 'public'. This might lead to data being written to an unintended or incorrect dataset.fixAlways explicitly define the target BigQuery dataset for assets or ops using `BigQueryIOManager` via the `dataset` config, `key_prefix` for assets, or output `metadata={'schema': '...'}` for ops. affects: All versions
deprecatedAPIs marked as 'preview' or 'beta' (e.g., `PipesDataprocJobClient`) are not considered ready for production use and may introduce breaking changes in patch or minor releases.fixAvoid using 'preview' or 'beta' APIs in production environments. If used, be prepared for frequent breaking changes and thoroughly test after every update.
affects: Specific components, check documentation for 'preview' or 'beta' markers.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'dagster_gcp'
The 'dagster-gcp' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install dagster-gcp'.
ImportError: cannot import name 'BigQueryIOManager' from 'dagster_gcp'
The 'BigQueryIOManager' class is not available in the 'dagster_gcp' module, possibly due to an outdated version.
fixEnsure the latest version of 'dagster-gcp' is installed: 'pip install --upgrade dagster-gcp'.
AttributeError: module 'dagster_gcp' has no attribute 'BigQueryResource'
The 'BigQueryResource' attribute does not exist in the 'dagster_gcp' module, possibly due to a version mismatch.
fixVerify the correct usage and ensure compatibility between 'dagster' and 'dagster-gcp' versions.
TypeError: 'NoneType' object is not callable
A misconfiguration or missing resource in the 'dagster_gcp' setup leads to a NoneType being called.
fixCheck the configuration of GCP resources and ensure all required parameters are correctly set.
google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials
The application default credentials are not set up for Google Cloud authentication.
fixSet up the application default credentials by running: 'gcloud auth application-default login'.
Upgrade
Version history
0.29.20latest on PyPI · released Aug 27, 2026
Audit
Dependencies
dagsterrequiredCore Dagster framework is required for functionality.
pythonrequiredRequires Python 3.10 or higher, but less than 3.15.
dataprocoptionalOptional dependency for Dataproc integration.
pyarrowoptionalOptional dependency, potentially for optimized data handling with certain I/O managers.