docs/en/platform/integrations/google-cloud-storage.md
The Google Cloud Storage integration connects your GCS buckets to Ultralytics Platform. Your images stay in your buckets — Platform indexes them in place, so you can browse, annotate, and train YOLO models without uploading a copy.
!!! note "Pro feature"
Google Cloud Storage datasets require a [Pro or Enterprise plan](../account/billing.md#plans). Free workspaces see the integration and are prompted to upgrade when connecting. Existing Google Cloud Storage datasets stay fully accessible if a subscription ends — only new connections and imports require Pro.
Platform only ever reads from your storage — it never writes, modifies, or deletes your objects. Create a dedicated service account with read access only:
roles/storage.objectViewer) role on the buckets you want to connect.!!! note "Bucket discovery needs one more permission"
`roles/storage.objectViewer` covers everything Platform does with your data, but it does not allow listing the
buckets in a project. Add a role carrying `storage.buckets.list` if you want Platform to find your buckets for you;
otherwise type each bucket name manually when connecting.
<!-- screenshot -->
You need the workspace admin or owner role to connect cloud storage. One connection carries up to 50 buckets, and discovery lists up to 300 of the buckets the service account can see.
Your browser reads the pasted key file and sends only the three fields Platform needs — client_email, private_key,
and project_id. The rest of the JSON never leaves the page.
Reconnecting the same service account later adds new buckets to the existing integration. A saved credential is only replaced once its replacement can still read every bucket you've already connected.
!!! note "Credential security"
Credentials are encrypted at rest with AES-256-GCM, are never returned to the browser, and are never exposed to training workloads. To revoke access, delete the service account key in Google Cloud.
Platform lists the folder once and indexes what it finds:
.jpg, .jpeg, .png, .webp, and .avif objects are indexed with dimensions read through bounded
requests. Platform does not persist a second copy of the source image..txt sidecars are parsed into Platform annotations, matched by the standard images/ → labels/ layout or as same-folder siblings.data.yaml and data.yml are preferred when the folder holds several.train, val, and test folder names in the object path assign splits automatically.The dataset then behaves like any other: browse and annotate it, set it public or private, share it with your team, and train on it through managed training. Originals are streamed on demand, and indexed images do not consume your Platform storage quota.
!!! note "Limits"
A single import indexes up to 50,000 objects, and label or YAML files up to 1 MB each. Larger buckets should be split across multiple datasets.
!!! warning "Keep indexed objects immutable"
Every indexed image is pinned to its GCS object generation, and Platform fails closed if an object changes underneath it. Add new objects instead of overwriting existing ones.
If an import fails — an empty folder, a typo in the path, or revoked permissions — the dataset shows the error on its page. Editors can click Retry import to restart it with the stored bucket and folder, or create a new dataset pointing at the corrected path.
A retry re-lists the folder rather than resuming: objects added since the first attempt are picked up, and objects that are no longer there are dropped from the dataset.
Managed training works through the normal training flow. Training uses Platform's own copies of the pinned images for the duration of the run, and your Google Cloud credentials are never exposed to training workloads.
Disconnecting deletes the stored credentials without touching anything in Google Cloud. Datasets built from those buckets stay in your workspace with their classes, labels, and annotations, but their images cannot be loaded, previewed, or trained on until the same service account is connected again.
Use the REST API with the integration ID returned by GET /api/integrations/buckets:
curl -X DELETE \
-H "Authorization: Bearer YOUR_API_KEY" \
https://platform.ultralytics.com/api/integrations/buckets/INTEGRATION_ID
from ultralytics_platform import Platform
client = Platform() # reads ULTRALYTICS_API_KEY
integrations = client.storage_integrations.list()
client.storage_integrations.delete("INTEGRATION_ID")
To revoke access at the source instead, delete the service account key in Google Cloud.
GCS-backed datasets currently exclude features that require Platform-owned copies of your images: auto-annotation, clustering analysis, dataset cloning, and immutable version snapshots.
Deleting a GCS-backed dataset, or individual images from it, removes Platform's references only — your objects are never touched.
Also see the Amazon S3 and Azure Blob Storage integrations.