{"id":5843,"library":"alibabacloud-oss-v2","title":"Alibaba Cloud OSS SDK V2 for Python","description":"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.","status":"active","version":"1.2.5","language":"en","source_language":"en","source_url":"https://github.com/aliyun/alibabacloud-oss-python-sdk-v2","tags":["cloud storage","alibaba cloud","oss","object storage","sdk"],"install":[{"cmd":"pip install alibabacloud-oss-v2","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The `oss2` package refers to the previous major version (V1) of the Alibaba Cloud OSS SDK. `alibabacloud-oss-v2` is the current, incompatible V2.","wrong":"import oss2","symbol":"Client","correct":"from alibabacloud_oss_v2 import client as oss_client\nfrom alibabacloud_oss_v2 import models as oss_models\nfrom alibabacloud_oss_v2 import config as oss_config\nfrom alibabacloud_oss_v2.credentials import EnvironmentVariableCredentialsProvider"}],"quickstart":{"code":"import os\nfrom alibabacloud_oss_v2 import client as oss_client\nfrom alibabacloud_oss_v2 import models as oss_models\nfrom alibabacloud_oss_v2 import config as oss_config\nfrom alibabacloud_oss_v2.credentials import EnvironmentVariableCredentialsProvider\n\n# Set environment variables for authentication (replace with your actual region and credentials)\n# os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'] = 'your_access_key_id'\n# os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'] = 'your_access_key_secret'\n# os.environ['ALIBABA_CLOUD_REGION_ID'] = 'cn-hangzhou'\n\nregion = os.environ.get('ALIBABA_CLOUD_REGION_ID', 'cn-hangzhou')\n\ntry:\n    # Loading credentials from environment variables\n    credentials_provider = EnvironmentVariableCredentialsProvider()\n\n    # Using the SDK's default configuration\n    cfg = oss_config.load_default()\n    cfg.credentials_provider = credentials_provider\n    cfg.region = region\n\n    client = oss_client.Client(cfg)\n\n    # Create a Paginator for the ListBuckets operation\n    paginator = client.list_buckets_paginator()\n\n    print(f\"Listing buckets in region: {region}\")\n    # Iterate through the bucket pages\n    found_buckets = False\n    for page in paginator.iter_page(oss_models.ListBucketsRequest()):\n        for bucket_info in page.buckets:\n            print(f'Bucket: {bucket_info.name}, Location: {bucket_info.location}, Creation Date: {bucket_info.creation_date}')\n            found_buckets = True\n    if not found_buckets:\n        print(\"No buckets found or access denied.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are set.\")","lang":"python","description":"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."},"warnings":[{"fix":"Rewrite V1 code using the new V2 API patterns, import paths (e.g., `alibabacloud_oss_v2` instead of `oss2`), and client initialization methods.","message":"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.","severity":"breaking","affected_versions":"< 1.0.0"},{"fix":"Update your code to use the new `MetaQueryMediaTypes` type for the `MetaQuery.media_types` attribute.","message":"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.","severity":"breaking","affected_versions":"1.1.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":">= 1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}