Download objects by streaming with the Python SDK - Object Storage Service

Streaming download retrieves an object in chunks rather than loading it entirely into memory. Use it for large objects or when you need to pipe the data directly to a file or another object.

All three examples below use bucket.get_object(), which returns a file-like object that is also iterable. The destination determines which pattern to apply: read into memory, write to a local file, or copy to another object in the same bucket.

Prerequisites

Before you begin, make sure you have:

An OSS bucket containing the object to download
The oss:GetObject permission on that bucket. For setup instructions, see Attach a custom policy to a RAM user
The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables set with your AccessKey credentials

Usage notes

The examples use the public endpoint for the China (Hangzhou) region (https://oss-cn-hangzhou.aliyuncs.com). If you access OSS from another Alibaba Cloud service in the same region, use the internal endpoint instead. See Regions and endpoints.
To create an OSSClient instance using a custom domain name or Security Token Service (STS), see Initialization.

Read into memory

Call object_stream.read() to load the full object content into memory. After reading, verify data integrity by comparing the client-side and server-side cyclic redundancy check (CRC) values.

This pattern loads the entire object into memory at once. For large objects, use the "Save to a local file" pattern below instead.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Load credentials from environment variables (OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET)
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Replace the endpoint with the one for your bucket's region
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# The region parameter is required for V4 signatures
region = "cn-hangzhou"

bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# get_object returns a file-like object; read() loads the full content into memory
# The full path must not include the bucket name
object_stream = bucket.get_object('exampleobject.txt')
print(object_stream.read())

# read() triggers CRC calculation -- always verify after calling it
if object_stream.client_crc != object_stream.server_crc:
    print("The CRC checksum between client and server is inconsistent!")

Save to a local file

Use shutil.copyfileobj() to write the stream directly to a local file without loading it into memory. This is the preferred pattern for large objects.

import shutil
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Load credentials from environment variables (OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET)
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Replace the endpoint with the one for your bucket's region
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# The region parameter is required for V4 signatures
region = "cn-hangzhou"

bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# The full path must not include the bucket name
object_stream = bucket.get_object('exampleobject.txt')

# shutil.copyfileobj streams data chunk by chunk -- no full in-memory load
# If the local file exists, it is overwritten; if not, it is created
# If no path is specified, the file is saved to the working directory of the project
with open('D:\\localpath\\examplefile.txt', 'wb') as local_fileobj:
    shutil.copyfileobj(object_stream, local_fileobj)

Copy to another object

Because get_object() returns an iterable, pass it directly to put_object() to stream the data into a new object in the same bucket.

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Load credentials from environment variables (OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET)
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Replace the endpoint with the one for your bucket's region
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# The region parameter is required for V4 signatures
region = "cn-hangzhou"

bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# The full path must not include the bucket name
object_stream = bucket.get_object('exampleobject.txt')

# Pass the iterable stream directly to put_object -- no intermediate file needed
bucket.put_object('exampleobjectnew.txt', object_stream)

What's next

For the complete sample code, see the GitHub example.
For the underlying API details, see GetObject.