You may fail to download a large object if the network is unstable or if the program stops responding. In some cases, you may still fail to download the object even after multiple attempts. To address this problem, OSS SDK for Go provides the resumable download feature.

To enable resumable download, you need to split the object you want to download into multiple parts and download them separately. After you have downloaded all parts, these parts will be combined into a complete object.

During the download, the download progress is recorded in a checkpoint file. If the download of a part fails, the next download starts from the position recorded in the checkpoint file. The checkpoint file is deleted after resumable download is complete.

  • The SDK records the download progress in the checkpoint file. Make sure that you have write permissions on the checkpoint file. The checkpoint file contains a checksum. This file cannot be edited. If the checkpoint file is damaged, you must download all parts again.
  • If the object being downloaded is modified (the ETag value of the object changes) or some parts are missing or modified, you must download the entire object again.

You can use Bucket.DownloadFile to download an object by using resumable download. The following table describes the parameters of this operation.

Parameter Description
objectKey The name of the object to be downloaded.
filePath The local file path to which to download the object.
partSize The size of each part. The part size ranges from 1 byte to 5 GB.
options The optional parameters, including:
  • Routines: the number of concurrent download threads. The default value is 1, indicating that only one thread is used to download parts.
  • Checkpoint: specifies whether resumable download is enabled and the path of the checkpoint file. By default, resumable download is disabled. For example, oss.Checkpoint(true, "") indicates that resumable download is enabled and the checkpoint file is the file.cp file contained in the same directory as the destination local file. file is a variable that indicates the local file name. You can also use oss.Checkpoint(true, "your-cp-file.cp") to specify the checkpoint file.
  • For more information about the conditions for resumable download, see Conditional download.

Run the following code for resumable download:

package main

import (

func main() {
    // Create an OSSClient instance.
    client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
    if err ! = nil {
        fmt.Println("Error:", err)

    // Specify the name of the bucket to download the object from.
    bucket, err := client.Bucket("<yourBucketName>")
    if err ! = nil {
        fmt.Println("Error:", err)

    // Start resumable download. Download the parts by using three threads concurrently.
    // yourObjectName is equivallent to objectKey and indicates the complete path of the object that you want to download from OSS. The path must include the file extension of the object. For example, you can set yourObjectName to abc/efg/123.jpg.
    // LocalFile is the filePath value. 100*1024 is the partSize value.
    err = bucket.DownloadFile("<yourObjectName>", "LocalFile", 100*1024, oss.Routines(3), oss.Checkpoint(true, ""))
    if err ! = nil {
        fmt.Println("Error:", err)