Install & Compatibility
Where this runs
tested against v1.9.44 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.540s · 32.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.516s · 34MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CosConfig
✓ from qcloud_cos import CosConfig
CosS3Client
✓ from qcloud_cos import CosS3Client
CosServiceError
✓ from qcloud_cos import CosServiceError
CosClientError
✓ from qcloud_cos import CosClientError
This quickstart demonstrates how to initialize the COS client and list existing buckets. It retrieves credentials from environment variables (recommended for security) and includes basic error handling.
import os
import logging
from qcloud_cos import CosConfig, CosS3Client, CosServiceError
logging.basicConfig(level=logging.INFO, stream=os.sys.stdout)
secret_id = os.environ.get('TENCENTCLOUD_SECRET_ID', '')
secret_key = os.environ.get('TENCENTCLOUD_SECRET_KEY', '')
region = os.environ.get('TENCENTCLOUD_REGION', 'ap-beijing') # Example region
token = None # Use None for permanent keys, provide if using temporary keys
if not secret_id or not secret_key:
print("Please set TENCENTCLOUD_SECRET_ID and TENCENTCLOUD_SECRET_KEY environment variables.")
else:
try:
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token)
client = CosS3Client(config)
# Example: List buckets
response = client.list_buckets()
print("Successfully listed buckets:")
for bucket_info in response.get('Buckets', []):
print(f" Bucket Name: {bucket_info.get('Name')}, Creation Date: {bucket_info.get('CreationDate')}")
except CosServiceError as e:
print(f"COS Service Error: {e.get_status_code()} - {e.get_error_code()} - {e.get_error_msg()}")
except CosClientError as e:
print(f"COS Client Error: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingThe older `cos-python-sdk` (without '-v5') is deprecated and uses an outdated JSON API. Users must upgrade to `cos-python-sdk-v5`, which uses the XML API.fixUninstall `cos-python-sdk` and install `cos-python-sdk-v5`. Update import paths and client initialization as per v5 documentation.
affects: <1.0.0 (for old SDK)
gotchaThe `Appid` parameter has been removed from `CosConfig`. The Appid should now be appended to the `Bucket` name when making calls (e.g., `examplebucket-1250000000`).fixRemove `Appid` from `CosConfig` initialization. When specifying a bucket, ensure it's in the format `BucketName-Appid`.
affects: All v5 versions
gotchaAvoid creating a new `CosS3Client` instance for each operation. It is recommended to create only one instance per region and reuse it for multiple operations (e.g., looping uploads/downloads) to prevent excessive connections and threads.fixInitialize `CosS3Client` once and reuse the instance throughout your application's lifecycle for operations within the same region.
affects: All v5 versions
gotchaFor security, it is highly recommended to use sub-account keys and environment variables to call the SDK, following the principle of least privilege. If permanent secret keys are used, restrict their permissions to the minimum necessary.fixConfigure sub-account IAM permissions with the least privilege. Store `SecretId` and `SecretKey` in environment variables (`TENCENTCLOUD_SECRET_ID`, `TENCENTCLOUD_SECRET_KEY`) or a secure configuration management system.
affects: All v5 versions
Upgrade
Version history
1.9.44latest on PyPI · released May 29, 2026
Audit
Dependencies
Python 2.7, 3.4+requiredSupported Python versions for the SDK.