{"id":674,"library":"oss2","title":"Aliyun OSS (Object Storage Service) SDK","description":"The `oss2` library is the official Alibaba Cloud OSS (Object Storage Service) SDK for Python. It provides functionalities to interact with OSS, including bucket and object operations like upload, download, and management. The current version is 2.19.1. It is actively maintained with regular updates.","status":"active","version":"2.19.1","language":"python","source_language":"en","source_url":"https://github.com/aliyun/aliyun-oss-python-sdk","tags":["cloud","storage","aliyun","oss","object-storage"],"install":[{"cmd":"pip install oss2","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for underlying HTTP communication.","package":"requests","optional":false},{"reason":"Used for CRC (Cyclic Redundancy Check) calculations.","package":"crcmod","optional":false}],"imports":[{"note":"Primary import for the SDK classes and functions.","symbol":"oss2","correct":"import oss2"},{"note":"Used for authentication with AccessKeyID and AccessKeySecret.","symbol":"Auth","correct":"from oss2 import Auth"},{"note":"Represents an OSS bucket, used for bucket and object operations.","symbol":"Bucket","correct":"from oss2 import Bucket"},{"note":"Iterator for listing objects within a bucket.","symbol":"ObjectIterator","correct":"from oss2 import ObjectIterator"},{"note":"Contains custom exceptions thrown by the SDK, e.g., `oss2.exceptions.NoSuchKey`.","symbol":"exceptions","correct":"from oss2 import exceptions"}],"quickstart":{"code":"import os\nimport oss2\n\n# Environment variables for credentials\nACCESS_KEY_ID = os.environ.get('OSS_ACCESS_KEY_ID', 'your-access-key-id')\nACCESS_KEY_SECRET = os.environ.get('OSS_ACCESS_KEY_SECRET', 'your-access-key-secret')\nENDPOINT = os.environ.get('OSS_ENDPOINT', 'http://oss-cn-hangzhou.aliyuncs.com') # e.g., 'http://oss-cn-hangzhou.aliyuncs.com'\nBUCKET_NAME = os.environ.get('OSS_BUCKET_NAME', 'your-bucket-name')\n\n# Ensure credentials and endpoint are set\nif not all([ACCESS_KEY_ID, ACCESS_KEY_SECRET, ENDPOINT, BUCKET_NAME]):\n    print(\"Please set OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET, OSS_ENDPOINT, and OSS_BUCKET_NAME environment variables.\")\n    exit(1)\n\ntry:\n    # Initialize Auth and Bucket\n    auth = oss2.Auth(ACCESS_KEY_ID, ACCESS_KEY_SECRET)\n    bucket = oss2.Bucket(auth, ENDPOINT, BUCKET_NAME)\n\n    # Object key\n    key = 'hello_oss.txt'\n    content = 'Hello Alibaba Cloud OSS!'\n\n    # 1. Upload an object from memory\n    bucket.put_object(key, content)\n    print(f\"Object '{key}' uploaded successfully.\")\n\n    # 2. Download the object content\n    response = bucket.get_object(key)\n    downloaded_content = response.read().decode('utf-8')\n    print(f\"Content of '{key}': {downloaded_content}\")\n\n    # 3. List objects in the bucket (optional)\n    print(\"\\nObjects in bucket:\")\n    for obj_info in oss2.ObjectIterator(bucket):\n        print(f\"  - {obj_info.key}\")\n\n    # 4. Delete the object\n    bucket.delete_object(key)\n    print(f\"Object '{key}' deleted successfully.\")\n\nexcept oss2.exceptions.OssError as e:\n    print(f\"OSS Error: {e.code} - {e.message} (Request ID: {e.request_id})\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize the `oss2` SDK, upload a string to an object, download its content, list objects in the bucket, and then delete the uploaded object. It uses environment variables for secure credential management."},"warnings":[{"fix":"Migrate your code to use the `oss2` API. If you have an old `oss` installation, ensure you are importing `oss2` and not `oss`.","message":"The `oss2` library is a complete rewrite of the previous Alibaba Cloud OSS Python SDK (version 0.x). It is not backward compatible. The package name was specifically changed to `oss2` to avoid conflicts with older installations.","severity":"breaking","affected_versions":"All versions 2.x compared to 0.x"},{"fix":"Ensure that only one instance (program or thread) is performing a resumable operation on a specific object-to-local-file pair at any given time.","message":"When using `oss2.resumable_download` or `oss2.resumable_upload`, avoid calling these functions concurrently from multiple programs or threads targeting the same object and local file. This can lead to checkpoint file corruption, overwrites, or temporary file naming conflicts.","severity":"gotcha","affected_versions":"All versions 2.x"},{"fix":"Configure a custom domain name (CNAME) and bind it to your bucket for data API operations. If using HTTPS, ensure a valid SSL certificate is bound to the custom domain.","message":"For new OSS users accessing buckets in Chinese mainland regions, a custom domain name (CNAME) is required for data API operations starting March 20, 2025. Default public endpoints are restricted for these operations.","severity":"gotcha","affected_versions":"New OSS users (registered after March 20, 2025) accessing Chinese mainland regions."},{"fix":"Use supported Python versions, preferably Python 3.5+.","message":"Python 2.6 and Python 3.3.0/3.3.1 are not recommended due to lack of core team support for 2.6 and a known Python issue (Issue 16658) for 3.3.0/3.3.1.","severity":"deprecated","affected_versions":"All versions 2.x when used with Python 2.6, 3.3.0, or 3.3.1"},{"fix":"Verify that the `AccessKeyId` and `AccessKeySecret` used to initialize the OSS client are correct and belong to an active Alibaba Cloud account. Ensure there are no typos, leading/trailing spaces, or incorrect characters. If the issue persists, generate new credentials in the Alibaba Cloud console or contact support.","message":"The provided Alibaba Cloud OSS Access Key ID is invalid or does not exist in Alibaba Cloud's records. This error prevents any further operations with OSS.","severity":"breaking","affected_versions":"All versions 2.x"},{"fix":"Thoroughly review network connectivity to Alibaba Cloud OSS endpoints. Verify that the OSS client is initialized with the correct region, endpoint URL, and bucket name. Ensure API credentials are valid and properly configured. Check for any firewall rules, proxy settings, or DNS issues that might prevent successful communication. Enable verbose logging for the OSS SDK if possible to capture more detailed diagnostic information regarding the underlying cause of the empty error.","message":"A generic and empty 'OSS Error' without a specific message or request ID was encountered. This indicates a fundamental issue during interaction with the OSS service where error details could not be retrieved or were suppressed by the SDK. This can be caused by low-level network connectivity problems, incorrect endpoint or bucket configuration, or an unhandled exception within the SDK before specific error details can be reported.","severity":"breaking","affected_versions":"All versions 2.x"}],"env_vars":null,"last_verified":"2026-05-12T17:44:26.001Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Run `pip install oss2` in your terminal to install the library.","cause":"The `oss2` library is not installed in the Python environment where the code is being executed.","error":"ModuleNotFoundError: No module named 'oss2'"},{"fix":"Verify that your `AccessKeyId`, `AccessKeySecret`, and `endpoint` are correct and match the bucket's region. Ensure your `oss2` library is updated to the latest version.\n\nExample:\n```python\nimport oss2\nimport os\n\naccess_key_id = os.environ.get('OSS_ACCESS_KEY_ID') # Or replace with your actual AccessKeyId\naccess_key_secret = os.environ.get('OSS_ACCESS_KEY_SECRET') # Or replace with your actual AccessKeySecret\nendpoint = 'https://oss-cn-hangzhou.aliyuncs.com' # Replace with your bucket's region-specific endpoint\nbucket_name = 'your-bucket-name'\n\nauth = oss2.Auth(access_key_id, access_key_secret)\nbucket = oss2.Bucket(auth, endpoint, bucket_name)\n```","cause":"The AccessKey ID, AccessKey Secret, or the endpoint used to initialize the `oss2` client is incorrect, or the SDK version is outdated, leading to a mismatch in the signature calculated by the client and the OSS server.","error":"SignatureDoesNotMatch"},{"fix":"Double-check the object name (key) and the bucket name to ensure they are correct and exist in your Alibaba Cloud OSS.\n\nExample of safe object access:\n```python\nimport oss2\n# ... (auth and bucket initialization)\n\nobject_name = 'non_existent_file.txt'\ntry:\n    bucket.get_object(object_name)\n    print(f'Object {object_name} found and retrieved.')\nexcept oss2.exceptions.NoSuchKey:\n    print(f'Object {object_name} does not exist.')\nexcept oss2.exceptions.ServerError as e:\n    print(f'Server error: {e.status}, Code: {e.code}, Message: {e.message}')\n```","cause":"The specified object key does not exist in the OSS bucket, or the bucket itself does not exist.","error":"oss2.exceptions.NoSuchKey"},{"fix":"Verify your network connectivity, check for correct endpoint URL and region, and ensure no firewalls or proxy settings are blocking access. You may also increase the connection timeout in the `oss2.Bucket` initialization if the network is slow.\n\nExample with increased timeout:\n```python\nimport oss2\n# ... (auth initialization)\n\nendpoint = 'https://oss-cn-hangzhou.aliyuncs.com'\nbucket_name = 'your-bucket-name'\n\nbucket = oss2.Bucket(auth, endpoint, bucket_name, connect_timeout=120) # Increase timeout to 120 seconds\n```","cause":"This error typically indicates underlying network issues, such as DNS resolution failure, connection timeouts, or other HTTP-level problems during communication with the OSS service.","error":"oss2.exceptions.RequestError"},{"fix":"Verify your `AccessKeyId`, `AccessKeySecret`, `endpoint`, and ensure the associated RAM user/role has the necessary OSS permissions for the specific bucket and object operations.","cause":"The provided Alibaba Cloud AccessKeyId, AccessKeySecret, or the associated user's permissions are incorrect or insufficient for the requested OSS operation.","error":"oss2.exceptions.ClientError: HTTP Status: 403, ErrorCode: AccessDenied"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"2.19.1","cli_name":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":null,"import_time_s":1.03,"mem_mb":19.1,"disk_size":"53.3M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.99,"mem_mb":18.8,"disk_size":"52.2M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":5.8,"import_time_s":0.78,"mem_mb":19.1,"disk_size":"54M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":18.9,"disk_size":"53M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":null,"import_time_s":1.32,"mem_mb":22,"disk_size":"58.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.47,"mem_mb":21.2,"disk_size":"56.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":5.3,"import_time_s":1.23,"mem_mb":22,"disk_size":"59M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.16,"mem_mb":21.3,"disk_size":"58M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":null,"import_time_s":1.17,"mem_mb":21,"disk_size":"47.4M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.21,"mem_mb":20.8,"disk_size":"46.4M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":8.5,"import_time_s":1.22,"mem_mb":21,"disk_size":"48M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.32,"mem_mb":20.9,"disk_size":"47M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":null,"import_time_s":1.1,"mem_mb":22,"disk_size":"47.2M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.14,"mem_mb":21.9,"disk_size":"46.0M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":7.5,"import_time_s":1.21,"mem_mb":22,"disk_size":"48M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.21,"mem_mb":21.9,"disk_size":"47M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":null,"import_time_s":1,"mem_mb":19.9,"disk_size":"53.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.02,"mem_mb":19.9,"disk_size":"52.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":6.6,"import_time_s":1.05,"mem_mb":19.9,"disk_size":"54M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.91,"mem_mb":19.9,"disk_size":"53M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}