{"id":4046,"library":"ibm-cos-sdk","title":"IBM Cloud Object Storage SDK for Python","description":"The IBM Cloud Object Storage SDK for Python (ibm-cos-sdk) is a Python package allowing developers to interact with IBM Cloud Object Storage. It is a fork of the popular boto3 library, adapted for IBM Cloud's IAM authentication, and provides an S3-compatible API. The library is actively maintained with frequent updates, currently at version 2.16.1, adding features like S3 Object Lock Governance Mode and Checksums Support.","status":"active","version":"2.16.1","language":"en","source_language":"en","source_url":"https://github.com/IBM/ibm-cos-sdk-python","tags":["ibm","cloud","object-storage","s3-compatible","boto3"],"install":[{"cmd":"pip install ibm-cos-sdk","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core functionality for IBM Cloud Object Storage SDK.","package":"ibm-cos-sdk-core","optional":false},{"reason":"Handles S3-like data transfer operations.","package":"ibm-cos-sdk-s3transfer","optional":false},{"reason":"Query language for JSON, used internally by the SDK.","package":"jmespath","optional":false}],"imports":[{"note":"The IBM COS SDK is a fork of boto3. For IBM Cloud Object Storage, you must import `ibm_boto3` instead of `boto3`. Using `boto3` will target AWS services by default.","wrong":"import boto3","symbol":"ibm_boto3","correct":"import ibm_boto3"},{"note":"Required for configuring the client with specific IBM COS authentication and endpoint details.","symbol":"Config","correct":"from ibm_botocore.client import Config"}],"quickstart":{"code":"import os\nimport ibm_boto3\nfrom ibm_botocore.client import Config\n\n# --- Environment Variables (Replace with your actual credentials/endpoints) ---\n# Get these values from your IBM Cloud Object Storage service credentials.\n# Set them as environment variables or replace directly in code (not recommended for production).\nAPI_KEY = os.environ.get('IBM_COS_API_KEY_ID', 'YOUR_API_KEY_ID')\nSERVICE_INSTANCE_ID = os.environ.get('IBM_COS_RESOURCE_INSTANCE_ID', 'YOUR_SERVICE_INSTANCE_ID')\nAUTH_ENDPOINT = os.environ.get('IBM_COS_AUTH_ENDPOINT', 'https://iam.cloud.ibm.com/identity/token') # e.g., 'https://iam.cloud.ibm.com/identity/token'\nSERVICE_ENDPOINT = os.environ.get('IBM_COS_ENDPOINT', 'https://s3.us.cloud-object-storage.appdomain.cloud') # e.g., 'https://s3.us.cloud-object-storage.appdomain.cloud'\n\nif not all([API_KEY, SERVICE_INSTANCE_ID, AUTH_ENDPOINT, SERVICE_ENDPOINT]):\n    print(\"Error: Missing one or more required environment variables for IBM COS configuration.\")\n    print(\"Please set IBM_COS_API_KEY_ID, IBM_COS_RESOURCE_INSTANCE_ID, IBM_COS_AUTH_ENDPOINT, IBM_COS_ENDPOINT.\")\n    exit(1)\n\ntry:\n    # Create client object\n    cos_client = ibm_boto3.client(\n        's3',\n        ibm_api_key_id=API_KEY,\n        ibm_service_instance_id=SERVICE_INSTANCE_ID,\n        ibm_auth_endpoint=AUTH_ENDPOINT,\n        config=Config(signature_version='oauth'),\n        endpoint_url=SERVICE_ENDPOINT\n    )\n\n    print(\"Successfully connected to IBM Cloud Object Storage. Listing buckets...\")\n\n    # List buckets\n    response = cos_client.list_buckets()\n    for bucket in response['Buckets']:\n        print(f\"Bucket Name: {bucket['Name']}\")\n\n    # Example: Upload a simple text file\n    bucket_name = \"my-test-bucket-12345\" # Replace with an existing bucket or create a new one\n    object_name = \"hello_cos.txt\"\n    data = \"Hello from IBM COS Python SDK!\"\n    try:\n        cos_client.put_object(Bucket=bucket_name, Key=object_name, Body=data)\n        print(f\"Successfully uploaded '{object_name}' to bucket '{bucket_name}'.\")\n\n        # Example: Download the file\n        obj = cos_client.get_object(Bucket=bucket_name, Key=object_name)\n        downloaded_data = obj['Body'].read().decode('utf-8')\n        print(f\"Downloaded '{object_name}': {downloaded_data}\")\n\n    except cos_client.exceptions.NoSuchBucket:\n        print(f\"Warning: Bucket '{bucket_name}' not found. Skipping upload/download examples.\")\n    except Exception as e:\n        print(f\"An error occurred during object operations: {e}\")\n\nexcept Exception as e:\n    print(f\"Failed to connect to IBM Cloud Object Storage: {e}\")","lang":"python","description":"This quickstart demonstrates how to establish a connection to IBM Cloud Object Storage, list existing buckets, and perform basic file upload and download operations. It uses environment variables for secure credential handling. Ensure you replace placeholder values or set corresponding environment variables with your IBM Cloud API Key, resource instance ID, IAM authentication endpoint, and service endpoint."},"warnings":[{"fix":"Update `import boto3` to `import ibm_boto3` and `from botocore.client import Config` to `from ibm_botocore.client import Config` in your code.","message":"Migration from 1.x to 2.x versions of ibm-cos-sdk requires changing import statements from `boto3` to `ibm_boto3`. This was introduced in version 2.0 to allow co-existence with the official `boto3` library for AWS services.","severity":"breaking","affected_versions":"1.x -> 2.x"},{"fix":"Carefully provide the API key, service instance ID, authentication endpoint, and service endpoint, and ensure `Config(signature_version='oauth')` is passed to the client or resource creation. These details can be found in your IBM Cloud Object Storage service credentials.","message":"When creating a client, ensure all required IBM-specific parameters (`ibm_api_key_id`, `ibm_service_instance_id`, `ibm_auth_endpoint`, `endpoint_url`) are provided, and `config=Config(signature_version='oauth')` is included for API key authentication. Missing or incorrect parameters will result in authentication failures.","severity":"gotcha","affected_versions":"2.0+"},{"fix":"Upgrade your Python environment to version 3.8 or newer.","message":"Support for Python 2.7 and Python 3.4 has been dropped. Newer versions of the SDK require Python 3.8 or higher.","severity":"deprecated","affected_versions":"< 2.10.x"},{"fix":"Refer to the `ibm-cos-sdk` changelog and `setup.py` for the exact `boto3`/`botocore` versions it aligns with (e.g., `ibm-cos-sdk-core` and `ibm-cos-sdk-s3transfer` dependencies), and consult the IBM COS documentation for supported S3 API features.","message":"The SDK aligns with `boto3` and `botocore` versions, meaning while it offers an S3-compatible API, specific `boto3`/`botocore` versions used by `ibm-cos-sdk` might not always perfectly match the very latest AWS versions. Compatibility issues could arise if expecting exact feature parity or behavior from a specific `boto3` version.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}