Multipart Upload
Scenarios
In a multipart upload, an object is split into multiple parts and these parts are uploaded independently. After all parts are uploaded, OBS assembles them into a single object. Generally, if the size of an object reaches 100 MB, you should use multipart upload instead of simple upload. Multipart upload has the following advantages:
- Improved throughput: Uploading parts in parallel speeds up the upload and maximizes bandwidth utilization.
- Enhanced robustness against network instability: If a part fails to upload due to network issues, you only need to re-upload that specific part. There is no need to upload the entire object again, which saves both time and traffic.
- Uploading objects with unknown sizes: You can use multipart upload to upload an object with an unknown size. For example, in video surveillance scenarios, video files are created and uploaded in real time, so multipart upload is a good choice for uploading these files.
Constraints
- Folders do not support multipart upload.
- Each request can upload only one part, but multiple requests can be initiated at the same time.
- Constraints on parts:
Table 1 Constraints on parts Item
Constraints
Maximum object size
48.8 TB
Maximum number of parts for each upload task
10,000
Part number
1 to 10,000 (inclusive)
Part size
5 MB to 5 GB. The size of the last part is between 0 bytes and 5 GB.
Maximum number of parts returned in response to the request for listing uploaded parts
1,000
Maximum number of multipart uploads returned in response to the request for listing initiated multipart uploads
1,000
- If you use SSE-C in a multipart upload, you must include the key in the requests for initiating the multipart upload, uploading parts, and copying parts. All requests in this multipart upload must use the same key. The key is not required for completing the multipart upload. The complete object is encrypted using SSE-C.
- If you use SSE-KMS or SSE-OBS in a multipart upload, you only need to configure the encryption method, algorithm, and key in initiating the multipart upload.
Billing
- If you want to upload a large number of Deep Archive objects, you can upload them in the Standard storage class and then transition them to the Deep Archive storage class through lifecycle rules to lower the costs on PUT requests.
- After initiating a multipart upload and uploading one or more parts, you must complete or abort the multipart upload. This ensures that OBS frees up the space for storing the uploaded parts and stops billing you for the uploaded parts.
Permissions
Before performing a multipart upload, you must obtain the permissions listed in the following table.
| Operation | Required Permission |
|---|---|
| Initiate a multipart upload. | You must be the bucket owner or have the PutObject permission. |
| Upload parts. | You must be the bucket owner or have the PutObject permission. |
| Complete the multipart upload. | You must be the bucket owner or have the PutObject permission. |
| Copy parts. | You must be the bucket owner or have the PutObject and GetObject permissions. |
| List uploaded parts. | You must be the bucket owner or have the ListMultipartUploadParts permission. |
| List multipart uploads. | You must be the bucket owner or have the ListBucketMultipartUploads permission. |
| Abort the multipart upload. | You must be the bucket owner or have the AbortMultipartUpload permission. |
Important Notes
- If the local file changes during the upload, all parts need to be uploaded again.
- When concurrent upload operations are performed for the same part of an object, the server follows the Last Write Wins policy, where the Last Write is determined by the time the part's metadata was created. To ensure data accuracy, the client must use a locking mechanism to prevent concurrent uploads of the same part of an object. Locking is not required for concurrent uploads of different parts of an object.
- When uploading a large number of objects, do not name objects with sequential prefixes, such as timestamps or alphabetical order. Objects with sequential prefixes may cause a large number of object indexes to be stored in a specific storage partition. In such cases, if there are too many requests for the objects, the requests cannot be handled efficiently.
- It is advised to enable versioning to prevent objects with the same name from being overwritten. Versioning keeps multiple versions of an object in the same bucket. You can restore any historical version at any time.
Multipart Upload Process
| No. | Operation | Description |
|---|---|---|
| 1 | Split a file into parts. | On your local client, split a large file into multiple parts. Each part must be between 5 MB and 5 GB in size, except for the last part, which can be 0 bytes to 5 GB. |
| 2 | Initiate a multipart upload. | Initiate a multipart upload and obtain the upload ID. The ID is required for all subsequent operations in this multipart upload, such as uploading, assembling, and listing parts. When initiating a multipart upload, you need to specify the storage class, object ACL, and other object properties. Once specified, you do not need to specify them again when uploading or assembling parts later. |
| 3 | Upload parts. | Upload parts. You can upload parts independently and in any order. If your network is in good condition, you can upload parts concurrently to improve the upload speed and make full use of bandwidth. If a part fails to upload, you only need to upload that part again. The upload of other parts remains unaffected. To abort the upload, make an API call to abort the multipart upload and delete the uploaded parts. |
| 4 | Complete the multipart upload. | After all parts are uploaded, assemble the parts into a single, complete object. |
Ways to Use Multipart Upload
OBS Console, OBS Browser+, and obsutil encapsulate the detailed steps of multipart upload, so you can simply upload a file in multiple parts directly through the GUI or CLI. For details, see Using OBS Console to Perform Multipart Upload, Using OBS Browser+ to Perform Multipart Upload, and Using obsutil to Perform Multipart Upload. To perform multipart uploads using SDKs, refer to Using SDKs to Perform Multipart Upload. To help you better understand how multipart upload works, we will use API Explorer to call OBS APIs to demonstrate the complete process of performing a multipart upload through APIs.
Using APIs to Perform Multipart Upload
Step 1: Split a File into Parts
Split a file into parts on your local client.
- (Optional) Create a file of a specific size. Here, we create a 20 MB file named test.file. If you have prepared a file, skip this step.
Linux or macOS:
dd if=/dev/urandom of=test.file bs=1M count=20
On Windows, open CMD and run the following command:
fsutil file createnew test.file 20971520
- Split the file into parts. In this example, split the 20 MB test.file into five 4 MB parts. Each part is named test-part**, where ** is a number suffix from 00 to 04.
Linux or macOS:
split -b 4M -d test.file test-part
In the command, -b specifies the maximum size of each part, and -d indicates that the part name uses a numeric suffix, for example, test-part00.
On Windows, run the following commands in PowerShell:
$inputFile = "test.file" $outputFilePrefix = "test-part" $chunkSize = 4MB $fs = [System.IO.File]::OpenRead($inputFile) $buffer = New-Object byte[] $chunkSize $fileNumber = 0 while ($fs.Position -lt $fs.Length) { $bytesRead = $fs.Read($buffer, 0, $chunkSize) $outputFile = "{0}{1:D2}" -f $outputFilePrefix, $fileNumber $fileStream = [System.IO.File]::Create($outputFile) $fileStream.Write($buffer, 0, $bytesRead) $fileStream.Close() $fileNumber++ } $fs.Close() - After the split is complete, verify that all parts are present in the directory where the commands were executed. Parts created in this example are as follows.

Step 2: Initiate a Multipart Upload
Make an API call to initiate a multipart upload and obtain the multipart upload ID.
- Go to the InitiateMultipartUpload page of API Explorer.
- Set the API call parameters.
Parameter
Example Value
Description
object_key
test.file
The name of the object uploaded to the bucket. It refers to the entire object, not to any individual part.
bucket_name
example-bucket-a-intl
The bucket name. Click
to choose a bucket that stores your object.uploads
Leave it blank.
This parameter indicates that the API call initiates a multipart upload, rather than a standard POST upload. Click Leave Blank to leave the parameter blank.
- Click Debug.
- After the API call succeeds, obtain the upload ID from the response in the lower right corner of the page.
As shown in the following figure, the upload ID is 000001987D77252A002424CADFB90B1C.

Step 3: Upload Parts
Upload the parts obtained in 1 to the bucket.
- Go to the UploadPart page of API Explorer.
- Set the API call parameters.

Parameter
Example Value
Description
object_key
test.file
The name of the object uploaded to the bucket. It refers to the entire object, not to any individual part. Keep this name the same as the one set in 2.
bucket_name
example-bucket-a-intl
The bucket name. Click
to choose a bucket that stores your object. Keep this name the same as the one set in 2.partNumber
1
The part number. It must be an integer from 1 to 10000. A part number uniquely identifies a part and its position. Parts must be numbered in ascending order according to their position in the object. For example, if a 20 MB object is split into five parts, the first part is numbered 1, the second part 2, and so on.
If you upload a new part using the same part number as a previously uploaded part, the previously uploaded part will be overwritten.
uploadId
000001987D77252A002424CADFB90B1C
The upload ID, which must be the one obtained in 4.
Body
test-part00
The part to upload. Click
to select the part to upload. - Click Debug.
- After the API call succeeds, verify that a success message appears on the Debugging Result tab. The response shown in the lower right corner of the page includes the ETag value of the part.
- Repeat 2 to 3 to upload all parts.
- After the upload is complete, go to the ListParts page, set parameters, and click Debug to list all uploaded parts.
Parameter
Example Value
Description
object_key
test.file
The name of the object uploaded to the bucket. It refers to the entire object, not to any individual part. Keep this name the same as the one set in 2.
bucket_name
example-bucket-a-intl
The bucket name. Click
to choose a bucket that stores your object. Keep this name the same as the one set in 2.uploadId
000001987D77252A002424CADFB90B1C
The upload ID, which must be the one obtained in 4.
- Verify that all parts have been uploaded successfully and obtain the part numbers and ETag values of all parts.
If the response result in 6 contains all parts, the parts have been uploaded successfully. In this case, record the part numbers and ETag values of all parts. The recorded data will be used as the request parameters for completing the multipart upload in the next step.
Step 4: Complete the Multipart Upload
This step assembles the uploaded parts into an object.
- Go to the CompleteMultipartUpload page of API Explorer.
- Set the API call parameters.
Parameter
Example Value
Description
object_key
test.file
The name of the object uploaded to the bucket. It refers to the entire object, not to any individual part. Keep this name the same as the one set in 2.
bucket_name
example-bucket-a-intl
The bucket name. Click
to choose a bucket that stores your object. Keep this name the same as the one set in 2.uploadId
000001987D77252A002424CADFB90B1C
The upload ID, which must be the one obtained in 4.
Body
<CompleteMultipartUpload> <Part> <PartNumber>1</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f6877"</ETag> </Part> <Part> <PartNumber>2</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f8678"</ETag> </Part> <Part> <PartNumber>3</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f7687"</ETag> </Part> <Part> <PartNumber>4</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f7876"</ETag> </Part> <Part> <PartNumber>5</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f7786"</ETag> </Part> </CompleteMultipartUpload>The body must include the part numbers and ETag values of all parts. You can obtain the data by making a ListParts API call after all parts have been uploaded. For details, see 7. Alternatively, you can obtain the ETag value of each part from its upload response. For details, see 4.
CAUTION:If a part is omitted when a multipart upload is completed, the part will be deleted and cannot be recovered. For example, if 10 parts are uploaded but only nine are assembled, the omitted part will be deleted and cannot be recovered.
Therefore, before completing a multipart upload, list all uploaded parts and make sure that no part is omitted.
- Click Debug.
- After the API call succeeds, verify that a success message appears on the Debugging Result tab. The response includes the object name, bucket name, and ETag value of the complete object.

Related Operations
The following are operations related to multipart upload:
Best Practices
- Control concurrent uploads to balance speed and stability.
Multipart upload improves transfer speeds by uploading parts concurrently. However, higher concurrency does not always mean higher performance. Too many concurrent requests increase system load and cause network congestion, which slows uploads. Too few requests underuse available bandwidth. Determine the number of concurrent parts dynamically based on network bandwidth and device performance.
- Avoid sequential prefixes when naming objects.
OBS partitions objects based on the UTF-8 encoding range of their names. Object names with sequential prefixes (sorted by timestamp or in alphabetical order) can concentrate access on a single partition, creating hotspots. Hot partitions limit request rates and increase latency. Use object names with random prefixes to distribute requests evenly across partitions and achieve horizontal scaling. For details, see Suggestions on OBS Performance Optimization.
- Use resumable transfer for higher reliability.
Multipart uploads do not expire and can be paused and resumed. Each multipart upload is uniquely identified by an upload ID. If a part fails to be uploaded due to network jitter or device issues, you only need to reupload that part instead of the entire file, improving transfer efficiency.
Helpful Links
If you have over 48.8 TB of data to upload, refer to Migrating Local Data to OBS.
What is your overall rating for this page?
Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot



