Registry / gcp / prefect-gcp

prefect-gcp

JSON →
library0.6.21pypypi✓ verified 24d ago

Prefect GCP is an integration library that allows Prefect workflows to interact seamlessly with various Google Cloud Platform (GCP) services. It provides blocks and tasks for services like Google Cloud Storage, BigQuery, Secret Manager, Vertex AI, and Cloud Run. The library is currently at version 0.6.17 and generally follows the release cadence of the main Prefect orchestration engine.

pip install -U "prefect-gcp"
INSTALL
IMPORT
SIG · PREFECT-GCP
P
prefect-gcp
gcppythonv0.6.21
Install
27.8s avg
Import
10507ms
Disk
509MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.6.21 · 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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 12.192s · 397.2MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 27.8s · import 8.822s · 395MB
509MB installed
● package 509MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

GcpCredentials
from prefect_gcp import GcpCredentials
from prefect_gcp.credentials import GcpCredentials
While `prefect_gcp.credentials` is technically correct, the top-level import `from prefect_gcp import GcpCredentials` is more idiomatic and usually sufficient, as `GcpCredentials` is directly exposed.
GcsBucket
from prefect_gcp.cloud_storage import GcsBucket
from prefect.filesystems import GCS
The `prefect.filesystems.GCS` block is part of Prefect Core, but `prefect_gcp.cloud_storage.GcsBucket` in `prefect-gcp` uses the `google-cloud-storage` package directly and offers more robust functionality and configuration options specific to GCP.
BigQueryWarehouse
from prefect_gcp.bigquery import BigQueryWarehouse
GcpSecret
from prefect_gcp.secret_manager import GcpSecret

This quickstart demonstrates how to use the `GcpCredentials` block for authentication and the `GcsBucket` block to interact with Google Cloud Storage. It uploads a simple text string to a specified bucket and then downloads it. It's designed to be runnable by either using Application Default Credentials or by providing service account JSON via an environment variable.

import os import asyncio from prefect import flow, task from prefect_gcp import GcpCredentials from prefect_gcp.cloud_storage import GcsBucket from dotenv import load_dotenv # Load environment variables from .env file (if present) load_dotenv() @task async def upload_and_download_file(bucket_name: str, file_content: str, source_path: str, destination_path: str): """Uploads a string to GCS and downloads it to a different path.""" # Ensure GcpCredentials block exists, or create one for testing # In a real scenario, you'd load a pre-configured block: GcpCredentials.load("my-gcp-creds") # For quickstart, we use env vars for service account info if available service_account_info_str = os.environ.get('GCP_SERVICE_ACCOUNT_INFO') service_account_info = None if service_account_info_str: import json service_account_info = json.loads(service_account_info_str) gcp_credentials = GcpCredentials(service_account_info=service_account_info) await gcp_credentials.save('gcp-quickstart-creds', overwrite=True) # Ensure GcsBucket block exists, or create one for testing gcs_bucket_block = GcsBucket(bucket_name=bucket_name, gcp_credentials=gcp_credentials) await gcs_bucket_block.save('gcs-quickstart-bucket', overwrite=True) # Use the saved block in the flow gcs_block = await GcsBucket.load("gcs-quickstart-bucket") print(f"Uploading content to gs://{bucket_name}/{source_path}") await gcs_block.upload_from_bytes(file_content.encode('utf-8'), source_path) print("Upload complete.") print(f"Downloading content from gs://{bucket_name}/{source_path} to {destination_path}") downloaded_content = await gcs_block.read_bytes(source_path) print(f"Downloaded content: {downloaded_content.decode('utf-8')}") # Clean up the file (optional) # await gcs_block.rm(source_path) # print(f"Cleaned up gs://{bucket_name}/{source_path}") @flow(log_prints=True) async def gcp_storage_flow(bucket_name: str = "your-prefect-gcp-bucket-name"): file_content = "Hello from Prefect GCP!" source_path = "prefect-gcp-test.txt" destination_path = "downloaded-prefect-gcp-test.txt" await upload_and_download_file(bucket_name, file_content, source_path, destination_path) if __name__ == "__main__": # Set this environment variable or use actual service account info for testing # export GCP_SERVICE_ACCOUNT_INFO='{"type": "service_account", ...}' # Ensure you have a GCP bucket created and permissions for the service account # To run: # 1. pip install -U "prefect-gcp[cloud_storage]" python-dotenv # 2. prefect block register -m prefect_gcp # 3. Create a GCS bucket (e.g., 'my-prefect-gcp-bucket') # 4. Set GCP_SERVICE_ACCOUNT_INFO env var with your service account JSON, or rely on ADC. # 5. python your_script_name.py asyncio.run(gcp_storage_flow(bucket_name=os.environ.get("GCS_BUCKET_NAME", "your-prefect-gcp-bucket-name")))
Debug
Known issues
breakingThe `CloudRunJob` and `VertexAICustomTrainingJob` infrastructure blocks have been deprecated in favor of Cloud Run and Vertex AI workers. These blocks will not be available after September 2024. Users should migrate to the new worker-based execution model for deploying flows to these services.
fix
Migrate deployments to use Prefect workers (Cloud Run Worker or Vertex AI Worker) instead of the deprecated infrastructure blocks. Refer to Prefect's upgrade guides for detailed instructions.
affects: <=0.6.x
gotchaAlways register `prefect-gcp` blocks after installation using `prefect block register -m prefect_gcp` for them to be available in the Prefect UI and for `Block.load()` operations.
fix
Run `prefect block register -m prefect_gcp` in your environment after installing the library or any time new blocks are added.
affects: All
gotchaAuthentication with GCP services via `GcpCredentials` relies on Google's Application Default Credentials (ADC) by default if `service_account_file` or `service_account_info` are not provided. Ensure your environment (e.g., local machine, VM, Cloud Run service) has proper ADC configured or explicitly provide service account credentials. Missing or incorrect permissions on the service account are a common source of errors.
fix
Provide `service_account_file` (path to JSON key) or `service_account_info` (JSON content as dict) to `GcpCredentials` or ensure `GOOGLE_APPLICATION_CREDENTIALS` environment variable is set for ADC. Verify the service account has necessary roles (e.g., Storage Admin for GCS, BigQuery Data Editor for BigQuery).
affects: All
gotchaThere's a distinction between `prefect.filesystems.GCS` (from Prefect Core) and `prefect_gcp.cloud_storage.GcsBucket`. The latter, part of `prefect-gcp`, utilizes the `google-cloud-storage` package for more comprehensive functionality and is generally recommended for deeper GCP Cloud Storage integrations.
fix
For robust Google Cloud Storage interactions, prefer `from prefect_gcp.cloud_storage import GcsBucket`. If simple file system operations suffice, `prefect.filesystems.GCS` might be acceptable.
affects: All
gotchaFor production deployments, it's highly recommended to pin specific versions of `prefect` and `prefect-gcp` (e.g., `prefecthq/prefect-gcp:0.6.17-python3.12-prefect3.6.19`) in your Docker images or `requirements.txt` to ensure stability and avoid unexpected behavior from automatic updates.
fix
Specify exact versions for `prefect` and `prefect-gcp` in your dependency management files or Dockerfiles.
affects: All
Upgrade
Version history
0.6.21latest on PyPI · released Jul 15, 2026
Audit
Dependencies
prefectrequiredCore orchestration engine for which prefect-gcp provides integrations.
google-cloud-storageoptionalRequired for Cloud Storage functionality (installed with `[cloud_storage]` extra).
google-cloud-bigqueryoptionalRequired for BigQuery functionality (installed with `[bigquery]` extra).
google-cloud-secret-manageroptionalRequired for Secret Manager functionality (installed with `[secret_manager]` extra).
google-cloud-aiplatformoptionalRequired for Vertex AI functionality (installed with `[aiplatform]` extra).
Agent activity
37 hits · last 30 days
node
32
OpenAI (training)
2
Resources
prefect-gcp — pip install prefect-gcp · libregistry