Amazon S3 Integration

The Amazon S3 integration connects your S3 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. With AI features on, Platform can also use them for smart annotation, auto-annotation, similar-image search, and cloud training.

Create an IAM User#

Read access covers everything except image generation, which also creates objects. Platform never modifies or deletes your objects. Use a dedicated IAM user — never root credentials:

1. In the AWS console, go to IAM > Users and create a user with no console access.

2. Attach a policy granting list and read access to the buckets you want to connect:

   {
       "Version": "2012-10-17",
       "Statement": [
           { "Effect": "Allow", "Action": "s3:ListAllMyBuckets", "Resource": "*" },
           {
               "Effect": "Allow",
               "Action": ["s3:ListBucket", "s3:GetObject"],
               "Resource": ["arn:aws:s3:::my-bucket", "arn:aws:s3:::my-bucket/*"]
           }
       ]
   }

   s3:ListAllMyBuckets is optional — it lets Platform discover your buckets so you don't have to type their names.

   For image generation, also allow s3:PutObject:

   {
       "Effect": "Allow",
       "Action": "s3:PutObject",
       "Resource": [
           "arn:aws:s3:::my-bucket/generated/*",
           "arn:aws:s3:::my-bucket/*/generated/*",
           "arn:aws:s3:::my-bucket/.ultralytics-write-check"
       ]
   }

   S3 has no create-only permission, so this scopes writes to generated/ folders and the .ultralytics-write-check key Platform uses to test write access (that test is always rejected, so nothing is stored). Platform's own writes never overwrite.

3. Open the user's Security credentials tab, create an access key, and copy the access key ID and secret access key.

Connect to Platform#

1. Go to Settings > Integrations and select Amazon S3 from the integration list.
2. Enter the access key ID, secret access key, and bucket region (for example us-east-1).
3. Click Find available buckets, then select the buckets to connect. If the policy doesn't permit discovery, enter a known bucket name manually.
4. Click Connect. Platform verifies it can list and read each selected bucket before saving anything, and checks whether the key can also write to it with a request S3 always rejects, so nothing is stored.

Each connected credential has an AI features switch. After you change the IAM policy, connect the same IAM user again to recheck write access.

You need the workspace admin or owner role to connect cloud storage. You can add up to 50 buckets at a time, and discovery lists up to 300 of the buckets the key can see.

Reconnecting the same IAM user 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. If any bucket can't be read, the error names it, including buckets connected earlier with the same IAM user.

AI Features#

Each connected credential has an AI features switch in Settings > Integrations, on by default. While it's on, Ultralytics GPUs and AI model providers may use that credential's images for:

• SAM smart annotation, and single-image and batch auto-annotation
• Similar-image search and clustering analysis
• Cloud training
• Image generation, on buckets with write access

AI model providers are involved only for image generation, whose prompts Google Gemini plans from the source image, and for paid annotation models, which run on your workspace's own provider key. Platform keeps no copy of your images: features read them on demand, cloud training uses temporary copies for the duration of a run, and similar-image search keeps an embedding of each image, which is deleted when the image leaves Platform.

Turn the switch off to keep images off Ultralytics GPUs and AI model providers. Turning it off stops new AI work; work already running finishes. Datasets on that credential then show AI features off with a link back to these settings, and each unavailable feature explains why. Manual annotation, sharing, and local training keep working, and the labels, models, and search results you already created are kept.

You need the workspace admin or owner role to change the switch. You can also set it with the REST API, using the integration ID returned by GET /api/integrations/buckets:

curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"processing": false}' \
  https://platform.ultralytics.com/api/integrations/buckets/INTEGRATION_ID

Image Generation#

Generate similar images works on Amazon S3 datasets whose bucket the IAM user can write to, while AI features are on. Images you add are written to a generated/ folder inside the dataset's folder, then added to the dataset like any other indexed image. Platform only creates new objects there and never overwrites or deletes existing ones. If the action says it needs write access, grant it if needed and connect the same IAM user again in Settings > Integrations.

Create a Dataset from an S3 Bucket#

1. Click New Dataset and open the Cloud tab.
2. Pick a connected bucket and browse to the folder containing your data.
3. Confirm the folder, adjust the dataset name, and create the dataset.

Platform lists the folder once and indexes what it finds:

• Images — .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.
• Labels — YOLO .txt sidecars are parsed into Platform annotations, matched by the standard images/ → labels/ layout or as same-folder siblings.
• Metadata — a YAML file provides class names and pose keypoint shape, exactly like an archive upload. data.yaml and data.yml are preferred when the folder holds several.
• Task — a sample of the label files decides the task, so segment, pose, and OBB folders are recognized from their label shape rather than the task you picked in the dialog.
• Splits — train, val, and test folder names in the object key 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.

Failed Imports#

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.

Training#

Managed training works through the normal training flow while AI features are on. Training uses Platform's own copies of the pinned images for the duration of the run, and your AWS credentials are never exposed to training workloads. With AI features off, the training dialog explains why cloud training is unavailable and offers local training instead.

Disconnect a Connection#

Disconnecting deletes the stored credentials without touching anything in AWS. 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 IAM user is connected again. You can still rename them, edit their labels, or delete them while disconnected.

To disconnect, go to Settings > Integrations, select Amazon S3, click Disconnect next to the credential, and confirm. Opening one of its datasets then shows Amazon S3 Disconnected with a link back to these settings, and the dataset returns automatically once you reconnect.

You can also disconnect with the REST API, using 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, deactivate or delete the access key in AWS IAM.

Current Limitations#

S3-backed datasets exclude features that need Platform-owned copies of your images: dataset cloning, immutable version snapshots, face blurring, and pasting images from other datasets. Smart annotation, auto-annotation, similar-image search, clustering, cloud training, and image generation need AI features on.

Deleting an S3-backed dataset, or individual images from it, removes Platform's references only — your objects are never touched.

Also see the Google Cloud Storage and Azure Blob Storage integrations.

FAQ#