skip to navigation
skip to content

ibm-cos-sdk 2.0.0

IBM SDK for Python

# 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.

## Documentation

* [Core documentation for IBM COS](
* [Python API reference documentation](
* [REST API reference documentation](

For release notes, see the [CHANGELOG](

* [Example code](#example-code)
* [Building from source](#building-from-source)
* [Getting help](#getting-help)

## 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`.

## 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 Bluemix UI 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.

## 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:

* Read a quick start guide in [Bluemix Docs](
* Ask a question on [Stack Overflow]( and tag it with `ibm` and `object-storage`.
* Open a support ticket with [IBM Bluemix Support](
* If it turns out that you may have found a bug, please [open an issue](

## License

This SDK is distributed under the
[Apache License, Version 2.0](
see LICENSE.txt and NOTICE.txt for more information.  
File Type Py Version Uploaded on Size
ibm-cos-sdk-2.0.0.tar.gz (md5, pgp) Source 2017-12-01 45KB