Registry / gcp / google-cloud-storage-transfer

google-cloud-storage-transfer

JSON →
library1.21.0pypypi✓ verified 24d ago

The `google-cloud-storage-transfer` library is the official Python client for the Google Cloud Storage Transfer Service. It enables programmatic control over data transfers to and from Google Cloud Storage, supporting various sources including other cloud providers and on-premises systems. Currently at version 1.20.0, this library adheres to Google Cloud's frequent release cadence, often receiving updates alongside other Python client libraries in the `googleapis/google-cloud-python` monorepo.

pip install google-cloud-storage-transfer
INSTALL
IMPORT
SIG · GOOGLE-CLOUD-STORA
G
google-cloud-storage-transfer
gcppythonv1.21.0
Install
5.6s avg
Import
1588ms
Disk
68MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.21.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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.862s · 69.5MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 5.6s · import 1.314s · 68MB
68MB installed
● package 68MB
Code
Verified usage

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

StorageTransferServiceClient
from google.cloud.storage_transfer import StorageTransferServiceClient
from google.cloud.storagetransfer_v1 import StorageTransferServiceClient
The `_v1` suffix is often for older, more specific API versions; the top-level import is preferred for the latest stable client.

This quickstart demonstrates how to create and immediately run a one-time transfer job to move data from a Google Cloud Storage source bucket to a Google Cloud Storage sink bucket. It requires enabling the Storage Transfer Service API, setting up Application Default Credentials, and ensuring the service account has appropriate permissions to both buckets. Replace placeholder variables with your Google Cloud Project ID and GCS bucket names.

import os from google.cloud.storage_transfer import StorageTransferServiceClient def create_and_run_gcs_to_gcs_transfer_job( project_id: str, source_bucket_name: str, sink_bucket_name: str, job_description: str, ): """Creates and runs a one-time transfer job between two GCS buckets.""" client = StorageTransferServiceClient() # Transfer job configuration transfer_job = { "project_id": project_id, "description": job_description, "transfer_spec": { "gcs_data_source": {"bucket_name": source_bucket_name}, "gcs_data_sink": {"bucket_name": sink_bucket_name}, }, "status": "ENABLED", # Job is created in an enabled state } # Create the transfer job # The API might create the job as DISABLED and then ENABLE it, or directly ENABLED. # For a 'run now' quickstart, we often set it to ENABLED at creation. try: created_job = client.create_transfer_job(transfer_job=transfer_job) print(f"Created transfer job: {created_job.name}") # If the job is not already IN_PROGRESS (e.g., if set to ENABLED but not yet started) # we can explicitly run it. For a one-time job set to ENABLED, it should start automatically. # However, for demonstration, an explicit run call can be shown for clarity if desired # for existing jobs, but 'create' with ENABLED often triggers it immediately for one-time. print(f"Transfer job '{created_job.name}' initiated.") # For more complex job management (e.g., recurrent jobs), you'd interact more with job status and run_transfer_job except Exception as e: print(f"Error creating or running transfer job: {e}") # Example usage (replace with your actual project and bucket names) if __name__ == "__main__": # Ensure these environment variables are set or replace with actual values # For local development, `gcloud auth application-default login` often provides credentials. PROJECT_ID = os.environ.get("GCP_PROJECT_ID", "your-gcp-project-id") SOURCE_BUCKET = os.environ.get("GCP_SOURCE_BUCKET", "your-source-gcs-bucket") SINK_BUCKET = os.environ.get("GCP_SINK_BUCKET", "your-sink-gcs-bucket") JOB_DESCRIPTION = "My Python quickstart GCS to GCS transfer" if PROJECT_ID == "your-gcp-project-id" or SOURCE_BUCKET == "your-source-gcs-bucket" or SINK_BUCKET == "your-sink-gcs-bucket": print("Please set GCP_PROJECT_ID, GCP_SOURCE_BUCKET, and GCP_SINK_BUCKET environment variables or replace placeholder values.") else: create_and_run_gcs_to_gcs_transfer_job( PROJECT_ID, SOURCE_BUCKET, SINK_BUCKET, JOB_DESCRIPTION )
Debug
Known issues
gotchaThe Storage Transfer Service API must be explicitly enabled in your Google Cloud Project before use. Additionally, ensure proper authentication is configured, ideally using Application Default Credentials (ADC).
fix
Go to the Google Cloud Console, navigate to 'APIs & Services' > 'Library', search for 'Storage Transfer API', and enable it. For authentication, run `gcloud auth application-default login` locally, or ensure your deployment environment (e.g., GCE, Cloud Run) has a service account with necessary roles.
affects: All versions
gotchaThe service has specific quotas and limits, including rate limits (e.g., 600 requests/min/project) and a 5 TiB maximum object size for transfers to Cloud Storage. Exceeding these limits can lead to failures or throttling.
fix
Review the official 'Quotas & Limits' documentation for Storage Transfer Service. Implement exponential backoff for retries and design transfer jobs to stay within known limits. For very large transfers, consider splitting the data into multiple jobs.
affects: All versions
gotchaInsufficient IAM permissions are a common cause of transfer failures. The service account or user initiating the transfer needs permissions to create and manage transfer jobs, and read/write access to the source and destination resources.
fix
Grant the necessary IAM roles to the principal performing the transfer. For example, 'Storage Transfer Admin' for managing jobs, and 'Storage Object Viewer'/'Storage Object Creator'/'Storage Object Admin' for source/sink buckets as appropriate.
affects: All versions
breakingIf you are migrating from or encounter older code using the `google-api-services-storagetransfer` library, be aware that it's a legacy Google API Client Library. The `google-cloud-storage-transfer` is the recommended Cloud Client Library.
fix
Update your dependencies to `google-cloud-storage-transfer` and refactor client instantiation and method calls according to the Cloud Client Library's patterns. Consult the 'Migrating to the Storage Transfer Service Cloud Client Library' guide for specific changes.
affects: Projects using legacy libraries
gotchaWhen troubleshooting failed transfer jobs, it's crucial to enable and inspect logs to understand the root cause, especially for agent-based transfers (on-premises to cloud).
fix
Configure your transfer jobs to store logs (e.g., using `--log-dir` in gcloud CLI or equivalent API parameter). Review these logs in Cloud Logging for detailed error messages, such as permission issues, missing files, or network problems.
affects: All versions
gotchaUsing Python 3.9 or older versions with `google-cloud-storage-transfer` (and its dependencies like `google-api-core`, `google-auth`) will trigger `FutureWarning`s indicating that these Python versions are unsupported and will receive limited or no further updates. This may lead to unexpected behavior or lack of critical fixes in the future.
fix
Upgrade your Python environment to version 3.10 or newer. After upgrading Python, update all Google Cloud Client Libraries and their core dependencies (e.g., `google-api-core`, `google-auth`) to their latest compatible versions using `pip install --upgrade google-cloud-storage-transfer google-api-core google-auth`.
affects: Projects using Python 3.9 or older
gotchaUsers must provide valid Google Cloud Project ID, source bucket name, and destination bucket name for transfer operations. These are fundamental identifiers required to configure and execute transfer jobs.
fix
Ensure that the Google Cloud Project ID, source bucket name, and destination bucket name are correctly provided to your application, typically via environment variables (e.g., `GCP_PROJECT_ID`, `GCP_SOURCE_BUCKET`, `GCP_SINK_BUCKET`), or passed explicitly as parameters to the Storage Transfer Service client methods.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google.cloud.storage_transfer'
The `google-cloud-storage-transfer` Python package is not installed or not accessible in the current Python environment.
fix
pip install google-cloud-storage-transfer
Service lacked sufficient permissions, SERVICE_PERMISSION_FAILURE
The Google-managed service account used by Storage Transfer Service (typically `project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com`) does not have the necessary IAM permissions to access the source or destination resources.
fix
Grant the `Storage Transfer Service Agent` role (`roles/storagetransfer.serviceAgent`) to the service account on the project, and the `Storage Admin` role (`roles/storage.admin`) on all relevant source and destination buckets.
The destination bucket doesn't exist in Cloud Storage.
The specified destination bucket in the transfer job configuration either does not exist, or the Storage Transfer Service agent does not have permission to view or write to it.
fix
Verify the spelling and existence of the destination bucket, and ensure the Storage Transfer Service agent has the `Storage Admin` role on the destination bucket.
Upgrade
Version history
1.21.0latest on PyPI · released Jun 3, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
28 hits · last 30 days
node
24
OpenAI (training)
1
Resources
google-cloud-storage-transfer — pip install google-cloud-storage-transfer · libregistry