Updated on 2026-11-02 GMT+08:00

Resumable Upload

Scenarios

Uploading large files often fails due to poor network conditions or program breakdowns. Re-uploads not only waste resources, but may also fail again. To avoid such issues, you can use the resumable upload API, which works by dividing a file into multiple parts and then uploading them separately. This API helps save resources for re-uploads and improves efficiency by concurrent uploads.

Important Notes

  • To upload objects, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • If you want to know the regions where OBS is available and the mapping between regions and endpoints, refer to Regions and Endpoints.
  • The file uploaded by the resumable upload API must be larger than 100 KB in size.
  • When you use the SDK resumable upload API, you must enable the resumable upload option so that the SDK can read the progress of the previous upload when the process restarts.
  • SDKs record the status of resumable uploads in a checkpoint file. Make sure your program has write permissions for the checkpoint file.
  • Do not alter the verification data in a checkpoint file. If the checkpoint file is damaged, all parts will be uploaded again.
  • If the local file changes during the upload, all parts will be uploaded again.

Ways to Upload

You can use SDKs, OBS Browser+, or obsutil to perform resumable upload for objects. If your resumable upload initiated via an SDK API call fails, you only need to run the relevant code to restart the upload. To improve the upload success rate, OBS Browser+ and obsutil automatically use resumable upload for objects larger than 50 MB. The switch to resumable upload is transparent to you and does not change how you use OBS Console or tools. If an upload fails, simply try again.