Alibaba Cloud OSS SDK V2 for Python

raw JSON →
1.2.5 verified Tue Apr 14 auth: no python

alibabacloud-oss-v2 is the second major version of the Alibaba Cloud OSS (Object Storage Service) SDK for Python. It is a significant rewrite, aiming to simplify underlying operations like authentication, automatic request retries, and error handling, while offering flexible parameter configuration and advanced features such as paginators and transmission managers. The library is currently at version 1.2.5 and receives frequent updates, indicating active development.

pip install alibabacloud-oss-v2

Common errors

error ModuleNotFoundError: No module named 'alibabacloud_oss_v2' ↓
cause The 'alibabacloud-oss-v2' package is not installed in the Python environment.
fix
Install the package using pip: 'pip install alibabacloud-oss-v2'.
error ImportError: cannot import name 'base' from 'alibabacloud_oss_v2' ↓
cause Attempting to import a non-existent module or class named 'base' from 'alibabacloud_oss_v2'.
fix
Verify the correct import statement by consulting the official documentation for the appropriate module or class to import.
error AttributeError: module 'alibabacloud_oss_v2' has no attribute 'Bucket' ↓
cause The 'Bucket' class or function does not exist in the 'alibabacloud_oss_v2' module.
fix
Check the official documentation for the correct class or function name to use for bucket operations.
error TypeError: __init__() missing 1 required positional argument: 'endpoint' ↓
cause The 'endpoint' parameter was not provided when initializing a client or service in 'alibabacloud_oss_v2'.
fix
Provide the 'endpoint' argument when initializing the client: 'client = alibabacloud_oss_v2.Client(endpoint="your_endpoint")'.
error ValueError: Invalid access key ID or secret. ↓
cause The provided access key ID or secret is incorrect or invalid.
fix
Ensure that the correct access key ID and secret are used when initializing the client: 'client = alibabacloud_oss_v2.Client(access_key_id="your_access_key_id", access_key_secret="your_access_key_secret")'.

Warnings

breaking The `alibabacloud-oss-v2` SDK is a complete rewrite and is not compatible with the previous `aliyun-oss-python-sdk` (or `oss2`) SDK. Migrating from V1 to V2 will require significant code changes. ↓
fix Rewrite V1 code using the new V2 API patterns, import paths (e.g., `alibabacloud_oss_v2` instead of `oss2`), and client initialization methods.
breaking In version 1.1.3, the type of `MetaQuery.media_types` was changed to `MetaQueryMediaTypes`. This is a type-hinting or strict-typing breaking change if you were directly using this attribute. ↓
fix Update your code to use the new `MetaQueryMediaTypes` type for the `MetaQuery.media_types` attribute.
gotcha Starting March 20, 2025, new OSS users in Chinese mainland regions must use a custom domain name (CNAME) for data API operations, as default public endpoints are restricted. You must bind a valid SSL Certificate to your custom domain if accessing via HTTPS. ↓
fix For new deployments in affected regions, configure a custom domain (CNAME) and ensure an SSL certificate is bound for HTTPS access. Update your endpoint configuration to use the custom domain.
gotcha Avoid hardcoding Alibaba Cloud credentials directly in your code. It's a security best practice to use environment variables or Alibaba Cloud RAM roles for authentication. ↓
fix Set `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET` as environment variables. The SDK's `EnvironmentVariableCredentialsProvider` will automatically pick these up. For production, consider using RAM roles.
gotcha For uploading large files (typically >100MB to 5GB, depending on best practices), it's highly recommended to use multipart upload for better reliability and performance. ↓
fix Utilize the SDK's multipart upload functionality for larger objects. The SDK supports `put_object_with_stream_and_auto_compress_and_hash` or the `Copier` for managing multipart uploads.

Imports

Quickstart

This quickstart demonstrates how to initialize the OSS V2 client using environment variables for credentials and then list all accessible OSS buckets. Ensure you set `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET`, and `ALIBABA_CLOUD_REGION_ID` environment variables for authentication.

import os
from alibabacloud_oss_v2 import client as oss_client
from alibabacloud_oss_v2 import models as oss_models
from alibabacloud_oss_v2 import config as oss_config
from alibabacloud_oss_v2.credentials import EnvironmentVariableCredentialsProvider

# Set environment variables for authentication (replace with your actual region and credentials)
# os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'] = 'your_access_key_id'
# os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'] = 'your_access_key_secret'
# os.environ['ALIBABA_CLOUD_REGION_ID'] = 'cn-hangzhou'

region = os.environ.get('ALIBABA_CLOUD_REGION_ID', 'cn-hangzhou')

try:
    # Loading credentials from environment variables
    credentials_provider = EnvironmentVariableCredentialsProvider()

    # Using the SDK's default configuration
    cfg = oss_config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = region

    client = oss_client.Client(cfg)

    # Create a Paginator for the ListBuckets operation
    paginator = client.list_buckets_paginator()

    print(f"Listing buckets in region: {region}")
    # Iterate through the bucket pages
    found_buckets = False
    for page in paginator.iter_page(oss_models.ListBucketsRequest()):
        for bucket_info in page.buckets:
            print(f'Bucket: {bucket_info.name}, Location: {bucket_info.location}, Creation Date: {bucket_info.creation_date}')
            found_buckets = True
    if not found_buckets:
        print("No buckets found or access denied.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are set.")
last verified Tue Apr 14
next check Mon Jul 13