Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Release 2.0.0 Dec 1, 2017
ibm_boto3 Update version to 2.3.4.dev1 Oct 31, 2018
scripts Release 2.0.0 Dec 1, 2017
tests Release 2.0.0 Dec 1, 2017
.coveragerc Release 2.0.0 Dec 1, 2017
.gitignore Added IDEA project files to the gitignore. Oct 1, 2015
CHANGELOG.rst Release 2.3.3 Oct 31, 2018
LICENSE Update copyright year Jan 4, 2017 Release 2.0.0 Dec 1, 2017 Release 2.3.1 Oct 12, 2018
requirements-docs.txt Release 2.3.2 Oct 15, 2018
requirements.txt Release 2.3.2 Oct 15, 2018
setup.cfg Release 2.3.2 Oct 15, 2018 Release 2.3.2 Oct 15, 2018
tox.ini Release 2.3.2 Oct 15, 2018

IBM Cloud Object Storage - Python SDK

This package allows Python developers to write software that interacts with IBM Cloud Object Storage. It is a fork of the boto3 library and can stand as a drop-in replacement if the application needs to connect to object storage using an S3-like API and does not make use of other AWS services.


For release notes, see the CHANGELOG.

Quick start

You'll need:

  • An instance of COS.
  • An API key from IBM Cloud Identity and Access Management with at least Writer permissions.
  • The ID of the instance of COS that you are working with.
  • Token acquisition endpoint
  • Service endpoint

These values can be found in the IBM Cloud Console by generating a 'service credential'.

Getting the SDK

Install the library from PyPi using pip:

$ pip install ibm-cos-sdk

Example code

Create a file, replacing your own values for API key, instance ID, and bucket name:

import ibm_boto3
from ibm_botocore.client import Config

api_key = 'API_KEY'
service_instance_id = 'RESOURCE_INSTANCE_ID'
auth_endpoint = ''
service_endpoint = ''

new_bucket = 'NewBucket'
new_cold_bucket = 'NewColdBucket'

cos = ibm_boto3.resource('s3',


                        'LocationConstraint': 'us-cold'

for bucket in cos.buckets.all():

From the command line, run python You should see a list of your buckets.

Using a Service Credential

You can source credentials directly from a Service Credential JSON document generated in the IBM Cloud console saved to ~/.bluemix/cos_credentials. The SDK will automatically load these providing you have not explicitly set other credentials during client creation. If the Service Credential contain HMAC keys the client will use those and authenticate using a signature, otherwise the client will use the provided API key to authenticate using bearer tokens.

Aspera high-speed transfer (New)

It is now possible to use the IBM Aspera high-speed transfer service as an alternative method to managed transfers of larger objects. The Aspera high-speed transfer service is especially effective across long distances or in environments with high rates of packet loss. For more details, check out the IBM Cloud documentation.

Archive Tier Support (New)

You can automatically archive objects after a specified length of time or after a specified date. Once archived, a temporary copy of an object can be restored for access as needed. Restore time may take up to 15 hours.

An archive policy is set at the bucket level by calling the put_bucket_lifecycle_configuration method on a client instance. A newly added or modified archive policy applies to new objects uploaded and does not affect existing objects. For more detail, see the documentation.

Building from source

Assuming that you have Python and virtualenv installed, set up your environment and install the required dependencies like this instead of the pip install ibm-cos-sdk defined above:

$ git clone
$ cd ibm-cos-sdk-python
$ virtualenv venv
$ . venv/bin/activate
$ pip install -r requirements.txt
$ pip install -e .

Getting Help

Feel free to use GitHub issues for tracking bugs and feature requests, but for help please use one of the following resources:

Deprecation Notice

Deprecation Notice for IBM Cloud Object Storage Java and Python SDK Versions 1.x

As of March 31, 2018, IBM will no longer add new features to the IBM Cloud Object Storage Java SDK Versions 1.x and the IBM Cloud Object Storage Python SDK Versions 1.x. We will continue to provide critical bug fixes to the 1.x releases through May 31, 2018.

Versions 1.x for Java and Python SDK will no longer be supported after May 31, 2018.

If you are using the 1.x version of the Java or Python SDK, please upgrade to the latest IBM Cloud Object Storage SDK versions 2.x. Instructions on how to upgrade from SDK Java and Python 1.x can be found in the "Migrating from 1.x.x" section of corresponding Readme.

Note: The IBM Cloud Object Storage Node.js SDK is NOT affected by this change.

For questions, please open an issue:



Migrating from 1.x.x

The 2.0 release of the SDK introduces a namespacing change that allows an application to make use of the original boto3 library to connect to AWS resources within the same application or environment. To migrate from 1.x to 2.0 some changes are necessary.

  1. Update the requirements.txt, or from PyPI via pip install -U ibm-cos-sdk. Verify no older versions exist with pip list | grep ibm-cos.
  2. Update any import declarations from boto3 to ibm_boto3.
  3. If access to AWS APIs is needed, reinstall the original boto3 by updating the requirements.txt, or from PyPI via pip install boto3.


This SDK is distributed under the Apache License, Version 2.0, see LICENSE.txt and NOTICE.txt for more information.