This topic describes how to initialize Object Storage Service (OSS) SDK for Python.
Prerequisites
Access credentials are configured. For more information, see Configure access credentials.
Background information
Most operations of OSS SDK for Python are performed based on the oss2.Service and oss2.Bucket classes.
The oss2.Service class is used to list buckets.
The oss2.Bucket class is used to upload, download, and delete objects, and configure buckets.
When you initialize the oss2.Service and oss2.Bucket classes, you must specify the endpoint of the region in which the bucket is located. The oss2.Service class does not support access to buckets by using custom domain names that are mapped to the buckets. For more information about endpoints, see Regions and endpoints and Map custom domain names.
Initialize the oss2.Service class
For more information, see List buckets.
Initialize the oss2.Bucket class
(Recommended) Use the V4 signature algorithm
We recommend that you use the V4 signature algorithm which provides better security. If you use the V4 signature algorithm, include the region parameter. The region parameter must be an Alibaba Cloud Region ID. Example: cn-Hangzhou. You must also declare oss2.ProviderAuthV4. OSS SDK for Python 2.18.4 and later support V4 signatures.
The following sample code provides an example on how to use the endpoint of the region in which the bucket is located to initialize the oss2.Bucket class by using the V4 signature algorithm. For the sample code on how to use a custom domain name that is mapped to a bucket or use anonymous access to initialize the oss2.Bucket class by using the V4 signature algorithm, refer to the following sample code and change the variables.
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = 'yourEndpoint'
# Specify the region of the endpoint. Example: cn-hangzhou.
region = 'cn-hangzhou'
# Specify the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region) (Not recommended) Use the V1 signature algorithm
From March 1, 2025, the V1 signature algorithm of OSS is no longer available to new customers with new UIDs. From September 1, 2025, OSS no longer updates and maintains the V1 signature algorithm, and the V1 signature algorithm is no longer available for new buckets. Upgrade V1 signatures to V4 signatures at the earliest opportunity to prevent impact on your business.
Use an OSS endpoint to initialize the oss2.Bucket class
The following sample code provides an example on how to use an OSS endpoint to initialize the oss2.Bucket class: For more information about the OSS endpoints of different regions, see Regions and endpoints.
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the environment variables are configured.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = 'yourEndpoint'
# Specify the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket') Use a custom domain name to initialize the oss2.Bucket class
The following sample code provides an example on how to use a custom domain name to initialize the oss2.Bucket class: For more information, see Map a custom domain name to the default domain name of a bucket.
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the environment variables are configured.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the custom domain name that is mapped to the bucket. Example: example.com.
cname = 'http://example.com'
# Specify the name of the bucket and set is_cname to True to enable CNAME. CNAME is used to map a custom domain name to a bucket.
bucket = oss2.Bucket(auth, cname, 'examplebucket', is_cname=True) Use anonymous access to initialize the oss2.Bucket class
Anonymous users can read only buckets whose access control list (ACL) is public-read and read and write only buckets whose ACL is public-read-write. Anonymous users cannot perform operations that are related to the oss2.Bucket class.
The following sample code provides an example on how to initialize the oss2.Bucket class for the examplebucket bucket whose ACL is public-read-write:
# -*- coding: utf-8 -*-
import oss2
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = 'yourEndpoint'
# Specify the name of the bucket. Example: examplebucket.
bucket_name = 'examplebucket'
# Use anonymous access to initialize the oss2.Bucket class.
bucket = oss2.Bucket(oss2.AnonymousAuth(), endpoint, bucket_name)Parameters supported by the oss2.Bucket class
The following table describes the parameters that you can configure when you initialize the oss2.Bucket class.
Parameter | Example | Description | Method |
is_cname | True | Specifies whether the endpoint is a custom domain name. Valid values:
| oss2.Bucket(auth, cname, 'examplebucket', is_cname=True) |
session | mytestsession | The name of the session, which specifies that a new session is started. Default value: None. If you set this parameter to the name of an existing session, the session is reused. | oss2.Bucket(auth, endpoint, 'examplebucket', session=oss2.Session()) |
connect_timeout | 30 | The timeout period of a connection. Default value: 60. Unit: seconds. | oss2.Bucket(auth, endpoint, 'examplebucket', connect_timeout=30) |
app_name | mytool | The name of the application that uses OSS SDK for Python. By default, this parameter is left empty. If the parameter is not empty, specify the corresponding value in the User-Agent field. Important The string is passed as an HTTP header value and must comply with HTTP standards. | oss2.Bucket(auth, endpoint, 'examplebucket', app_name='mytool') |
enable_crc | False | Specifies whether to enable CRC-64. Default value: true.
| oss2.Bucket(auth, endpoint, 'examplebucket', enable_crc=False) |
Examples on how to configure the oss2.Bucket class
The following section provides examples on how to configure the oss2.Bucket class:
Configure the connection timeout period
The following sample code provides an example on how to configure the connection timeout period:
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# We recommend that you do not save access credentials in the project code. Otherwise, access credentials may be leaked. As a result, the security of all resources in your account is compromised. In this example, access credentials are obtained from environment variables. Before you run the sample code, make sure that the environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of the bucket and set the connection timeout period to 30 seconds.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', connect_timeout=30,region=region) Disable CRC-64
By default, CRC-64 is enabled to ensure data integrity when you upload or download objects.
We recommend that you do not disable CRC. If you disable CRC-64, data integrity may be affected when you upload or download objects.
The following sample code provides an example on how to disable CRC-64:
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# We recommend that you do not save access credentials in the project code. Otherwise, access credentials may be leaked. As a result, the security of all resources in your account is compromised. In this example, access credentials are obtained from environment variables. Before you run the sample code, make sure that the environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of the bucket and set enable_crc to False to disable CRC-64.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', enable_crc=False,region=region) Specify the connection pool size
The following sample code provides an example on how to specify the connection pool size:
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# We recommend that you do not save access credentials in the project code. Otherwise, access credentials may be leaked. As a result, the security of all resources in your account is compromised. In this example, access credentials are obtained from environment variables. Before you run the sample code, make sure that the environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the connection pool size. Default value: 10.
session = oss2.Session(pool_size=20)
# Specify the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', session=session,region=region)Specify the TLS version
Different TLS versions have different security and performance features. Select a TLS version based on your scenario.
You can specify the TLS version in OSS SDK for Python V2.18.1 or later.
The following sample code provides an example on how to set the TLS version to 1.2:
# -*- coding: utf-8 -*-
import ssl
import oss2
from requests.adapters import HTTPAdapter
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Configure the SSL adapter.
class SSLAdapter(HTTPAdapter):
def init_poolmanager(self, *args, **kwargs):
# Set the TLS version to 1.2.
kwargs["ssl_version"] = ssl.PROTOCOL_TLSv1_2
return super().init_poolmanager(*args, **kwargs)
# Create a session object and configure the adapter by using the session object.
session = oss2.Session(adapter=SSLAdapter())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of the bucket. Example: examplebucket.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', session=session, region=region)
# Upload the object.
bucket.put_object("example.txt", "hello")What to do next
After you initialize OSS SDK for Python, you can use the oss2.Service and the oss2.Bucket classes to initiate requests. For more information, see Get started with OSS SDK for Python.