> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload large objects with multipart uploads

> Upload large objects to AI Object Storage in parallel parts with high-level clients or the low-level S3 API.

A multipart upload (MPU) uploads one object as a set of independent parts, which CoreWeave AI Object Storage assembles into a single object when the upload completes. Use multipart uploads for large objects:

* Parts upload in parallel, which increases throughput.
* You can retry a failed part without restarting the whole upload.
* AI Object Storage preserves the parts, and [LOTA](https://docs.coreweave.com/products/storage/object-storage/improving-performance/about-lota.md) caches each part independently, so it can spread a multipart object across the cache of several Nodes and serve the parts in parallel. LOTA caches an object uploaded with a single `PutObject` call as one unit on one Node, which can create a read bottleneck for large objects. For more information, see [Use multipart uploads for large objects](https://docs.coreweave.com/products/storage/object-storage/improving-performance/best-practices.md#use-multipart-uploads-for-large-objects).

Multipart uploads are subject to the part size and part count [limits](https://docs.coreweave.com/products/storage/object-storage/manage-quotas.md#limits). Each part can be at most 5 GiB. All parts except the last must be at least 5 MiB. An upload can contain up to 10,000 parts. We recommend a part size of at least 50 MiB.

The following sections describe two ways to run a multipart upload: with a high-level client that manages the parts for you, or with the low-level API for direct control over each part.

## Prerequisites

Before you start, make sure you have:

* An [Access Key](https://docs.coreweave.com/products/storage/object-storage/auth-access/manage-access-keys/create-keys.md) for the organization that owns the bucket.
* An S3-compatible client [configured for AI Object Storage](https://docs.coreweave.com/products/storage/object-storage/using-object-storage/configure-endpoints.md) with virtual-hosted addressing.
* Permission to call [`s3:PutObject`](https://docs.coreweave.com/products/storage/object-storage/reference/object-storage-s3#s3createmultipartupload) on the bucket. The Rclone example also requires `s3:GetObject` to verify the uploaded object with `HeadObject`. Aborting an upload also requires [`s3:AbortMultipartUpload`](https://docs.coreweave.com/products/storage/object-storage/reference/object-storage-s3#s3abortmultipartupload), and listing uploads or parts requires `s3:ListBucketMultipartUploads` or `s3:ListMultipartUploadParts`, respectively.

## Upload with a high-level client

High-level clients switch to a multipart upload automatically when a file exceeds a size threshold, then split, upload, and complete the parts for you. For better performance, raise the default part size to 50 MiB.

> [tab] AWS CLI
>
> The AWS CLI uses a multipart upload for files larger than `multipart_threshold` and splits them into parts of `multipart_chunksize`. Both default to 8 MiB.
>
> 1. In your `cw` [profile](https://docs.coreweave.com/products/storage/object-storage/using-object-storage/s3-clients/aws.md), set both to 50 MiB:
>
>    ```bash title="Set the multipart threshold and part size with AWS CLI" theme={"system"}
>    aws configure set s3.multipart_threshold 50MB --profile cw
>    aws configure set s3.multipart_chunksize 50MB --profile cw
>    ```
>
> 2. Upload the file. Replace `LOCAL_FILE_PATH`, `BUCKET_NAME`, and `OBJECT_KEY` with your values.
>
>    ```bash title="Upload a large file with AWS CLI" theme={"system"}
>    aws s3 cp LOCAL_FILE_PATH s3://BUCKET_NAME/OBJECT_KEY --profile cw
>    ```

> [tab] Boto3
>
> The Boto3 `upload_file()` method uses a multipart upload for files larger than the `TransferConfig` threshold, which defaults to 8 MiB.
>
> 1. Set environment variables for your CoreWeave credentials:
>
>    ```bash theme={"system"}
>    export ACCESS_KEY_ID="ACCESS_KEY_ID_VALUE"
>    export SECRET_ACCESS_KEY="SECRET_ACCESS_KEY_VALUE"
>    ```
>
> 2. Replace `LOCAL_FILE_PATH`, `BUCKET_NAME`, and `OBJECT_KEY` with your values, then run the script:
>
>    ```python title="Upload a large file with Boto3" theme={"system"}
>    import os
>    import boto3
>    from boto3.s3.transfer import TransferConfig
>    from botocore.client import Config
>
>    MiB = 1024 * 1024
>
>    boto_config = Config(
>        region_name='US-EAST-04A',
>        s3={'addressing_style': 'virtual'}
>    )
>
>    s3 = boto3.client(
>        's3',
>        endpoint_url='https://cwobject.com',
>        aws_access_key_id=os.environ['ACCESS_KEY_ID'],
>        aws_secret_access_key=os.environ['SECRET_ACCESS_KEY'],
>        config=boto_config
>    )
>
>    transfer_config = TransferConfig(
>        multipart_threshold=50 * MiB,
>        multipart_chunksize=50 * MiB,
>        max_concurrency=10,
>    )
>
>    s3.upload_file(
>        'LOCAL_FILE_PATH',
>        'BUCKET_NAME',
>        'OBJECT_KEY',
>        Config=transfer_config,
>    )
>    ```

> [tab] s5cmd
>
> > [!NOTE]
> >
> > **Use the CoreWeave fork of `s5cmd` with AI Object Storage**
> >
> > The upstream [`s5cmd`](https://github.com/peak/s5cmd) uses path-style addressing with custom endpoint URLs. AI Object Storage doesn't support path-style addressing and requires virtual-hosted style URLs. Use the [CoreWeave fork of `s5cmd`](https://github.com/coreweave/s5cmd), which is compatible with AI Object Storage and can safely replace any existing `s5cmd` installation. For setup and usage, see [Migrate data to AI Object Storage](https://docs.coreweave.com/products/storage/object-storage/migrate-data.md#migrate-data-with-s5cmd).
>
> The CoreWeave fork of s5cmd uploads in 50 MiB parts by default. To set how many parts of each file upload in parallel, use `--concurrency`. The default is 5. s5cmd reads the credentials you [configured for s5cmd](https://docs.coreweave.com/products/storage/object-storage/migrate-data.md#configure-credentials). Replace `LOCAL_FILE_PATH`, `BUCKET_NAME`, and `OBJECT_KEY` with your values.
>
> ```bash title="Upload a large file with s5cmd" theme={"system"}
> s5cmd --endpoint-url https://cwobject.com \
>       cp --concurrency 16 LOCAL_FILE_PATH s3://BUCKET_NAME/OBJECT_KEY
> ```

> [tab] Rclone
>
> Rclone uses a multipart upload for files larger than `--s3-upload-cutoff`, which defaults to 200 MiB. Set `--s3-chunk-size` to 50 MiB (the default is 5 MiB), and use `--s3-upload-concurrency` to set how many parts of each file upload in parallel. Replace `REMOTE_NAME` with the name of your [Rclone remote](https://docs.coreweave.com/products/storage/object-storage/using-object-storage/s3-clients/rclone.md), and replace `LOCAL_FILE_PATH`, `BUCKET_NAME`, and `OBJECT_KEY` with your values.
>
> ```bash title="Upload a large file with Rclone" theme={"system"}
> rclone copyto LOCAL_FILE_PATH REMOTE_NAME:BUCKET_NAME/OBJECT_KEY \
>       --s3-chunk-size 50M \
>       --s3-upload-concurrency 8
> ```

When the upload finishes, the file appears in the bucket as a single object.

To tune concurrency for bulk transfers, see [Optimize s5cmd performance](https://docs.coreweave.com/products/storage/object-storage/migrate-data.md#optimize-s5cmd-performance) and [Optimize Rclone performance](https://docs.coreweave.com/products/storage/object-storage/migrate-data.md#optimize-rclone-performance).

## Upload parts with the low-level API

When you need direct control over the upload, for example to upload parts from different processes or machines, use the low-level API. A low-level multipart upload has three steps:

1. [`CreateMultipartUpload`](https://docs.coreweave.com/products/storage/object-storage/reference/object-storage-s3#s3createmultipartupload) starts the upload and returns an `UploadId`.
2. [`UploadPart`](https://docs.coreweave.com/products/storage/object-storage/reference/object-storage-s3#s3uploadpart) uploads each part with a part number from 1 to 10,000 and returns an `ETag` for that part.
3. [`CompleteMultipartUpload`](https://docs.coreweave.com/products/storage/object-storage/reference/object-storage-s3#s3completemultipartupload) assembles the object from a list of the part numbers and `ETag` values, sorted by part number in ascending order.

The following Boto3 script uploads a local file in 50 MiB parts, one part at a time. To upload parts in parallel, call `upload_part()` from multiple threads or processes with the same `UploadId`. If any step fails, the script aborts the upload so the parts don't remain in the bucket. With 50 MiB parts, an upload can hold up to about 488 GiB. For larger files, increase `PART_SIZE`.

1. Set environment variables for your CoreWeave credentials:

   ```bash theme={"system"}
   export ACCESS_KEY_ID="ACCESS_KEY_ID_VALUE"
   export SECRET_ACCESS_KEY="SECRET_ACCESS_KEY_VALUE"
   ```

2. Replace `LOCAL_FILE_PATH`, `BUCKET_NAME`, and `OBJECT_KEY` with your values, then run the script:

   ```python title="Multipart upload with the low-level Boto3 API" theme={"system"}
   import os
   import boto3
   from botocore.client import Config

   BUCKET = 'BUCKET_NAME'
   KEY = 'OBJECT_KEY'
   FILE_PATH = 'LOCAL_FILE_PATH'
   PART_SIZE = 50 * 1024 * 1024  # 50 MiB

   boto_config = Config(
       region_name='US-EAST-04A',
       s3={'addressing_style': 'virtual'}
   )

   s3 = boto3.client(
       's3',
       endpoint_url='https://cwobject.com',
       aws_access_key_id=os.environ['ACCESS_KEY_ID'],
       aws_secret_access_key=os.environ['SECRET_ACCESS_KEY'],
       config=boto_config
   )

   upload_id = s3.create_multipart_upload(Bucket=BUCKET, Key=KEY)['UploadId']

   try:
       parts = []
       with open(FILE_PATH, 'rb') as f:
           part_number = 1
           while chunk := f.read(PART_SIZE):
               response = s3.upload_part(
                   Bucket=BUCKET,
                   Key=KEY,
                   UploadId=upload_id,
                   PartNumber=part_number,
                   Body=chunk,
               )
               parts.append({'PartNumber': part_number, 'ETag': response['ETag']})
               part_number += 1

       s3.complete_multipart_upload(
           Bucket=BUCKET,
           Key=KEY,
           UploadId=upload_id,
           MultipartUpload={'Parts': parts},
       )
       print(f"Uploaded {FILE_PATH} to {BUCKET}/{KEY} in {len(parts)} parts.")
   except Exception:
       s3.abort_multipart_upload(Bucket=BUCKET, Key=KEY, UploadId=upload_id)
       raise
   ```

The object appears in the bucket only after `CompleteMultipartUpload` succeeds.

## Clean up incomplete uploads

A client can stop before it calls `CompleteMultipartUpload` or `AbortMultipartUpload`, for example because the process crashes or loses its connection. The uploaded parts then remain in the bucket as an incomplete multipart upload. Incomplete uploads consume storage, don't appear in normal object listings, and prevent the bucket from being deleted: `DeleteBucket` returns `BucketNotEmpty`.

You can remove incomplete uploads in the following ways:

* To find and remove existing incomplete uploads, see [Abort incomplete multipart uploads](https://docs.coreweave.com/products/storage/object-storage/buckets/abort-multipart-uploads.md).
* To remove them automatically, add an [`AbortIncompleteMultipartUpload` lifecycle rule](https://docs.coreweave.com/products/storage/object-storage/buckets/lifecycle-policies#common-configurations) to every bucket that receives large uploads.
