Install & Compatibility
Where this runs
tested against v9.35.1 · 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 1.770s · 318.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 19.6s · import 1.096s · 304MB
334MB installed
● package 334MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
gcp
✓ import pulumi_gcp as gcp
✗ import gcp
The Pulumi GCP provider is installed as `pulumi_gcp` and conventionally aliased as `gcp` for brevity and clarity when referencing resources.
storage
✓ from pulumi_gcp import storage
Specific modules for resource types (e.g., `storage`, `compute`, `sql`) are imported from `pulumi_gcp`.
This quickstart program creates a Google Cloud Storage bucket. Before running, ensure you have the Pulumi CLI installed, are authenticated to GCP via `gcloud auth application-default login`, and have run `pulumi new gcp-python` to set up a project. You may need to set the `gcp:project` configuration value using `pulumi config set gcp:project <YOUR_GCP_PROJECT_ID>` or set the `GCP_PROJECT_ID` environment variable.
import pulumi
from pulumi_gcp import storage
import os
# Configure the GCP project ID (replace with your project ID or set via pulumi config)
# pulumi config set gcp:project my-gcp-project-id
project_id = os.environ.get('GCP_PROJECT_ID') or pulumi.Config('gcp').get('project')
# Create a GCP Storage Bucket
# Note: Bucket names must be globally unique.
bucket = storage.Bucket(
'my-unique-bucket-name',
project=project_id, # Ensure project_id is configured or passed
location='US-CENTRAL1', # Specify a region or multi-region
uniform_bucket_level_access=True # Recommended best practice for security
)
# Export the bucket's self_link and URL
pulumi.export('bucket_self_link', bucket.self_link)
pulumi.export('bucket_url', bucket.url)
pulumi --version
Debug
Known issues
breakingPulumi GCP Provider v9.0.0 introduced several breaking changes. Key changes include: `gcp.alloydb.Cluster` now defaults `deletionProtection` to `true`. The import behavior for `gcp.storage.Bucket` labels changed; labels are no longer directly imported to the `labels` field but appear in `effectiveLabels` and must be explicitly set. `gcp.tpu.Node` was removed in favor of `gcp.tpu.V2Vm`. Several resource fields received increased validation. `gcp.storage.Notification` topic format requires a full resource path.fixReview the official 'GCP 9.0 Migration Guide' on the Pulumi Registry. Explicitly set `deletionProtection` where needed. Manually manage `gcp.storage.Bucket` labels post-import. Migrate `gcp.tpu.Node` to `gcp.tpu.V2Vm`. Update resource configurations to comply with new validation rules and format requirements.
affects: >=9.0.0
breakingPulumi GCP Provider v8.0.0 introduced changes primarily related to deletion protection and labeling. The `deletionProtection` field was added with a default of `true` for several resources (e.g., `gcp.cloudrunv2.Service`, `gcp.organizations.Project`) to prevent accidental deletion. The `template.containers[].ports` field in `gcp.cloudrunv2.Service` changed from a list to an object type. A new default provisioning label `goog-pulumi-provisioned` is now added to all resources, appearing in `pulumiLabels` and `effectiveLabels` outputs.fixConsult the 'GCP 8.0 Migration Guide'. Explicitly configure `deletionProtection` to `false` if you intend for resources to be destroyable. Adjust `cloudrunv2.Service` port configurations. To opt out of the default label, set `pulumi config set gcp:addPulumiAttributionLabel false`.
affects: >=8.0.0 <9.0.0
breakingPulumi GCP Provider v7.0.0 introduced a significant rework of label handling. The `labels` field became non-authoritative, managing only the labels defined in your Pulumi configuration. New output-only fields `pulumiLabels` (merges config labels with global defaults) and `effectiveLabels` (all labels on the GCP resource) were added. This can lead to unexpected diffs on upgrade, but these are typically safe 'output-only' changes.fixRefer to the 'GCP 7.0 Migration Guide'. Understand the new label semantics: if you rely on all GCP-managed labels appearing in your Pulumi state, you now need to inspect `effectiveLabels`. While direct label changes often don't require code modification for Python, be aware of the new output fields and their impact on diffs.
affects: >=7.0.0 <8.0.0
gotchaThe Pulumi GCP provider relies on the Google Cloud SDK (`gcloud CLI`) being installed and authenticated on the machine where Pulumi commands are run. Lack of proper authentication (e.g., `gcloud auth application-default login`) or incorrect project configuration can lead to authentication errors or resources being deployed to an unintended project.fixEnsure `gcloud CLI` is installed and updated. Run `gcloud auth application-default login` to authenticate. Set the target GCP project using `pulumi config set gcp:project <YOUR_PROJECT_ID>` or by providing it as an argument to resources where applicable.
affects: All versions
gotchaUnexpected resource recreation or 'perpetual diffs' can occur, especially after provider updates or due to subtle API changes in GCP's underlying services. This can result in `pulumi up` always showing changes even if the user's code has not changed.fixCheck the Pulumi GCP GitHub Issues for known bugs or 'awaiting-upstream' issues that match your symptoms. Consult migration guides for recent major versions, as 'spurious diffs' fixes are often implemented. If a resource perpetually updates, inspect the `pulumi preview --diff` output carefully to understand the exact difference Pulumi perceives. Sometimes, refreshing the state (`pulumi refresh`) can resolve minor inconsistencies.
affects: All versions (may be more frequent with major provider updates)
Errors
Common errors & fixes
googleapi: Error 403: Permission denied
The authenticated GCP identity (user account or service account) lacks the necessary IAM permissions to perform the requested operation on the specified resource or project.
fixGrant the appropriate IAM roles and permissions to the service account or user initiating the Pulumi deployment. Ensure the `gcloud` CLI is configured with the correct project and account, and that the Pulumi environment variables (e.g., `GOOGLE_APPLICATION_CREDENTIALS`) point to a service account with sufficient privileges.
Plan apply failed: project: required field is not set
The Pulumi program or stack configuration does not specify the target GCP project ID, which is required for Pulumi to interact with GCP correctly.
fixSet the GCP project ID using `pulumi config set gcp:project <YOUR_PROJECT_ID>` or by providing it directly in the provider configuration within your Pulumi program.
Cannot determine region: set in this resource, or set provider-level 'region' or 'zone'
The Pulumi program or stack configuration does not specify a default geographical region or zone for resources, which is often required by GCP services.
fixSet the default GCP region or zone using `pulumi config set gcp:region <YOUR_GCP_REGION>` or `pulumi config set gcp:zone <YOUR_GCP_ZONE>`, or specify them explicitly on individual resources.
ModuleNotFoundError: No module named 'pulumi_gcp'
The `pulumi_gcp` Python package is not installed or not accessible within the active Python environment where the Pulumi program is being executed.
fixActivate your Python virtual environment (if using one) and install the `pulumi_gcp` package using `pip install pulumi_gcp`. Ensure that `pulumi` is also installed.
error: already exists
The Pulumi program is attempting to create a resource in GCP that already exists under the same name or identifier. This can happen after a failed previous deployment, manual creation, or an incorrect import attempt.
fixIf the resource should be managed by Pulumi, use `pulumi import <type_token> <name> <existing_id>` to bring it into the stack state. If the resource should be newly created, change its logical name in the Pulumi program. If the existing resource is no longer needed, delete it manually from GCP before running `pulumi up`.
Upgrade
Version history
9.35.1latest on PyPI · released Aug 24, 2026
Audit
Dependencies
pulumirequiredCore Pulumi SDK for infrastructure orchestration.
gcloud CLIrequiredRequired for authentication and underlying GCP interactions, must be installed and authenticated separately.