All Products
Search
Document Center

Object Storage Service:Copy an object (Go SDK V1)

Last Updated:Jan 05, 2026

This topic describes how to copy an object within a bucket or across buckets in the same region.

Usage notes

  • In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.

  • In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.

  • This topic demonstrates creating an OSSClient instance with an OSS endpoint. For alternative configurations, such as using a custom domain or authenticating with credentials from Security Token Service (STS), see Configure OSSClient instances.

  • To copy an object, you must have read permissions on the source object and read and write permissions on the destination bucket.

  • Make sure that no retention policies are configured for the source bucket and the destination bucket. Otherwise, the error message The object you specified is immutable. is returned.

  • The source bucket and destination bucket must be in the same region. For example, objects cannot be copied from a bucket located in the China (Hangzhou) region to another bucket located in the China (Qingdao) region.

Sample code

Copying small files

You can use the CopyObject method to copy an object to the same bucket or a different bucket in the same region. This method is recommended for objects smaller than 1 GB.

Copy an object within the same bucket

package main

import (
	"log"
	"time"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Failed to create credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, for the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region where the bucket is located. For example, for the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Failed to create OSS client: %v", err)
	}

	// Specify the bucket name, for example, examplebucket.
	bucketName := "examplebucket"
	// Specify the full path of the source object, for example, srcdir/srcobject.jpg.
	objectName := "srcdir/srcobject.jpg"
	// Specify the full path of the destination object, for example, destdir/destobject.jpg.
	destObjectName := "destdir/destobject.jpg"

	// Get the bucket.
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		log.Fatalf("Failed to get bucket '%s': %v", bucketName, err)
	}

	// Specify the metadata of the destination object.
	expires := time.Date(2049, time.January, 10, 23, 0, 0, 0, time.UTC)
	tag1 := oss.Tag{
		Key:   "a",
		Value: "1",
	}

	taggingInfo := oss.Tagging{
		Tags: []oss.Tag{tag1},
	}

	options := []oss.Option{
		oss.MetadataDirective(oss.MetaReplace),
		oss.Expires(expires),
		oss.SetTagging(taggingInfo),
		// Copy the tags of the source object to the destination object.
		// oss.TaggingDirective(oss.TaggingCopy),
		// Set the access control list (ACL) of the destination object to private.
		// oss.ObjectACL(oss.ACLPrivate),
		// Specify the customer master key (CMK) managed by KMS. This parameter is valid only when x-oss-server-side-encryption is set to KMS.
		// oss.ServerSideEncryptionKeyID("9468da86-3509-4f8d-a61e-6eab1eac****"),
		// Specify the server-side encryption algorithm that OSS uses to create the destination object.
		// oss.ServerSideEncryption("AES256"),
		// Copy the metadata of the source object to the destination object.
		// oss.MetadataDirective(oss.MetaCopy),
		// Specify whether to overwrite an existing destination object that has the same name. Set this to true to prevent overwriting.
		// oss.ForbidOverWrite(true),
		// If the ETag of the source object matches the ETag you provide, the copy operation is performed and 200 OK is returned.
		// oss.CopySourceIfMatch("5B3C1A2E053D763E1B002CC607C5****"),
		// If the ETag of the source object does not match the ETag you provide, the copy operation is performed and 200 OK is returned.
		// oss.CopySourceIfNoneMatch("5B3C1A2E053D763E1B002CC607C5****"),
		// If the specified time is earlier than the actual modification time of the object, the object is copied and 200 OK is returned.
		// oss.CopySourceIfModifiedSince(time.Date(2021, time.December, 9, 7, 1, 56, 0, time.UTC)),
		// If the specified time is the same as or later than the actual modification time of the object, the object is copied and 200 OK is returned.
		// oss.CopySourceIfUnmodifiedSince(time.Date(2021, time.December, 9, 7, 1, 56, 0, time.UTC)),
		// Specify the storage class of the object. Set this to Standard.
		// oss.StorageClass("Standard"),
	}

	// Copy the object and use the specified metadata for the destination object.
	_, err = bucket.CopyObject(objectName, destObjectName, options...)
	if err != nil {
		log.Fatalf("Failed to copy object from '%s' to '%s': %v", objectName, destObjectName, err)
	}

	log.Printf("Successfully copied object from '%s' to '%s'", objectName, destObjectName)
}

Copy an object between different buckets in the same region

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Failed to create credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, for the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region where the bucket is located. For example, for the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Failed to create OSS client: %v", err)
	}

	// Specify the source bucket name, for example, srcbucket.
	srcBucketName := "srcbucket"
	// Specify the full path of the source object, for example, srcobject.jpg.
	srcObjectName := "srcobject.jpg"
	// Specify the full path of the destination object, for example, destobject.jpg.
	dstObjectName := "destobject.jpg"
	// Specify the destination bucket name, for example, destbucket.
	destBucketName := "destbucket"

	// Get the destination bucket instance.
	bucket, err := client.Bucket(destBucketName)
	if err != nil {
		log.Fatalf("Failed to get bucket '%s': %v", destBucketName, err)
	}

	// Copy the srcobject.jpg object from the srcbucket bucket to the destobject.jpg object in the destbucket bucket.
	_, err = bucket.CopyObjectFrom(srcBucketName, srcObjectName, dstObjectName)
	if err != nil {
		log.Fatalf("Failed to copy object from '%s/%s' to '%s/%s': %v", srcBucketName, srcObjectName, destBucketName, dstObjectName, err)
	}

	log.Printf("Successfully copied object from '%s/%s' to '%s/%s'", srcBucketName, srcObjectName, destBucketName, dstObjectName)
}

Copying large files

The following code shows how to copy a large object:

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Failed to create credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, for the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region where the bucket is located. For example, for the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Failed to create OSS client: %v", err)
	}

	// Specify the bucket name, for example, examplebucket.
	bucketName := "examplebucket"

	// Get the bucket.
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		log.Fatalf("Failed to get bucket '%s': %v", bucketName, err)
	}

	// Specify the full path of the source object, for example, srcobject.txt.
	objectSrc := "srcobject.txt"
	// Specify the full path of the destination object, for example, destobject.txt.
	objectDest := "destobject.txt"
	// Specify the full path of the local file.
	fileName := "D:\\localpath\\examplefile.txt"

	// Split the file into multiple parts.
	chunks, err := oss.SplitFileByPartNum(fileName, 3)
	if err != nil {
		log.Fatalf("Failed to split file: %v", err)
	}

	// Upload the file to OSS.
	err = bucket.PutObjectFromFile(objectSrc, fileName)
	if err != nil {
		log.Fatalf("Failed to upload object '%s' from file '%s': %v", objectSrc, fileName, err)
	}

	// Initialize the multipart upload.
	imur, err := bucket.InitiateMultipartUpload(objectDest)
	if err != nil {
		log.Fatalf("Failed to initiate multipart upload for '%s': %v", objectDest, err)
	}

	var parts []oss.UploadPart
	for _, chunk := range chunks {
		// Set multipart upload options.
		options := []oss.Option{}

		// Perform the multipart copy.
		part, err := bucket.UploadPartCopy(imur, bucketName, objectSrc, chunk.Offset, chunk.Size, chunk.Number, options...)
		if err != nil {
			log.Fatalf("Failed to upload part %d of '%s': %v", chunk.Number, objectSrc, err)
		}
		parts = append(parts, part)
	}

	// Complete the multipart upload.
	cmur, err := bucket.CompleteMultipartUpload(imur, parts)
	if err != nil {
		log.Fatalf("Failed to complete multipart upload for '%s': %v", objectDest, err)
	}

	log.Printf("Multipart upload completed successfully for '%s'. cmur: %v", objectDest, cmur)
}

References

  • For the complete sample code for copying an object, see GitHub sample.

  • For more information about the API operation for copying a small object, see CopyObject.

  • For more information about the API operation for copying a large object, see UploadPartCopy.