Install & Compatibility
Where this runs
tested against v2.16.2 · 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.708s · 29.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.8s · import 0.646s · 30MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_session
✓ from ibm_botocore.session import get_session
✗ from ibm_cos_sdk_core.session import get_session
This quickstart demonstrates how to create a low-level S3-compatible client using `ibm-cos-sdk-core`'s session and client creation capabilities. It shows how to map IBM Cloud Object Storage credentials (API Key and Service Instance ID) to the `aws_access_key_id` and `aws_secret_access_key` parameters required by the S3-compatible client. The example then attempts to list available buckets. Most users are recommended to use the higher-level `ibm-cos-sdk` package for simpler interactions.
import os
from ibm_cos_sdk_core.session import get_session
# Configure IBM Cloud Object Storage credentials and endpoint
# These usually map to 'aws_access_key_id' and 'aws_secret_access_key' for S3 compatibility
IBM_API_KEY_ID = os.environ.get('IBM_COS_API_KEY_ID', 'YOUR_IBM_API_KEY')
IBM_SERVICE_INSTANCE_ID = os.environ.get('IBM_COS_SERVICE_INSTANCE_ID', 'YOUR_IBM_SERVICE_INSTANCE_ID')
IBM_COS_REGION = os.environ.get('IBM_COS_REGION', 'us-south')
IBM_COS_ENDPOINT = os.environ.get('IBM_COS_ENDPOINT', f'https://s3.{IBM_COS_REGION}.cloud-object-storage.appdomain.cloud')
if 'YOUR_' in IBM_API_KEY_ID or 'YOUR_' in IBM_SERVICE_INSTANCE_ID:
print("Please set IBM_COS_API_KEY_ID and IBM_COS_SERVICE_INSTANCE_ID environment variables for authentication.")
print("Falling back to dummy credentials. This example will likely fail without proper auth.")
# Get a session object
session = get_session()
# Create a low-level client for the S3-compatible service
# Note: IBM COS uses 's3' service model for its S3-compatible API
try:
client = session.create_client(
's3',
region_name=IBM_COS_REGION,
endpoint_url=IBM_COS_ENDPOINT,
aws_access_key_id=IBM_API_KEY_ID,
aws_secret_access_key=IBM_SERVICE_INSTANCE_ID
)
# Example: List buckets
print(f"Attempting to list buckets in region {IBM_COS_REGION}...")
response = client.list_buckets()
print("Buckets:")
for bucket in response.get('Buckets', []):
print(f" - {bucket['Name']}")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure your IBM COS credentials and endpoint are correctly configured.")
Debug
Known issues
gotchaMost users should install and use the `ibm-cos-sdk` package instead of `ibm-cos-sdk-core`. The core library is low-level, similar to `botocore`, and is primarily intended for extending the SDK or for very specific low-level interactions.fixFor most applications, use `pip install ibm-cos-sdk` and import from `ibm_boto3` instead of `ibm_cos_sdk_core`.
affects: All versions
gotchaCredential mapping for IBM COS S3-compatible API: The `ibm-cos-sdk-core` (like `botocore`) expects `aws_access_key_id` and `aws_secret_access_key`. For IBM COS, your IBM Cloud API Key should be provided as `aws_access_key_id`, and your IBM Cloud Service Instance ID should be provided as `aws_secret_access_key`.fixWhen creating a client, pass your IBM API Key to `aws_access_key_id` and your IBM Service Instance ID to `aws_secret_access_key`.
affects: All versions
gotchaThe API is low-level and requires manual handling of service models, operations, and response parsing, similar to `botocore`. This means more boilerplate code compared to the high-level client in `ibm-cos-sdk`.fixBe prepared to work with raw JSON responses and define explicit parameters for each API call. Consider using `ibm-cos-sdk` for a more Pythonic and abstracted interface.
affects: All versions
breakingThis library is tightly coupled with `botocore` versions. Breaking changes or new features introduced in `botocore` can directly impact `ibm-cos-sdk-core`'s behavior or require updates.fixMonitor `botocore` release notes and ensure compatibility when upgrading either `ibm-cos-sdk-core` or `botocore` dependencies in your project.
affects: All versions, especially major `botocore` upgrades
gotchaCorrect endpoint and region configuration are critical. IBM COS has various endpoints based on geographic regions. Using an incorrect endpoint or region for your bucket will result in connectivity or authorization errors.fixAlways specify the `endpoint_url` corresponding to your bucket's region and ensure `region_name` is also set appropriately.
affects: All versions
Upgrade
Version history
2.16.2latest on PyPI · released Apr 14, 2026
Audit
Dependencies
botocorerequiredProvides the underlying low-level client architecture and service definitions, this library is a fork/wrapper of botocore.
jmespathrequiredUsed for querying JSON data, a common dependency of botocore and related AWS/S3 compatible SDKs.