A newer version of this documentation is available.

View Latest

Install and Start Using the Python SDK with Couchbase Server

The Couchbase Python SDK allows Python applications to access a Couchbase cluster. The Python SDK offers a traditional synchronous API as well as integration with twisted, gevent, and asyncio. It depends on the C SDK and utilizes it for performance and reliability.

Installing on Linux

For installation on Linux, install the couchbase-release repository, and then install the libcouchbase packages. The following examples download and install couchbase-release repsitory, a C and C++ compiler, the C SDK development files (libcouchbase-devel [RPM] or libcouchbase-dev [DEB]), Python development files, and finally the Python SDK using pip.

Debian and Ubuntu
# Only needed during first-time setup:
wget http://packages.couchbase.com/releases/couchbase-release/couchbase-release-1.0-2-amd64.deb
sudo dpkg -i couchbase-release-1.0-2-amd64.deb
sudo apt-get update
sudo apt-get install libcouchbase-dev build-essential python-dev python-pip
sudo pip install couchbase
RHEL and CentOS
# Only needed during first-time setup:
wget http://packages.couchbase.com/releases/couchbase-release/couchbase-release-1.0-2-x86_64.rpm
sudo rpm -iv couchbase-release-1.0-2-x86_64.rpm
# Will install or upgrade existing packages
sudo yum install libcouchbase-devel gcc gcc-c++ python-devel python-pip
sudo pip install couchbase
RHEL/CentOS distributions may not provide the python-pip package in the base repositories. It may be found in the EPEL repository.

Installation on Mac OS X

To install the library on Mac OS X, first install the de-facto package manager for OS X: homebrew. Once homebrew is configured:

brew update # get list of latest packages
brew install libcouchbase
brew install python
pip install couchbase
The above example uses the Python supplied by homebrew and not the vendor-supplied Python which ships with OS X. The Python SDK will still work with the vendor-supplied Python (though pip install may be a privileged command), but it is recommended to use Homebrew’s Python instead.

Installing on Microsoft Windows

The Couchbase Python SDK is available as an executable installer for Windows. This contains all the required dependencies, including C SDK development files.

  1. Check your Windows architecture (32-bit or 64-bit) and make sure the required version of Python is installed.

  2. Download the Couchbase Python SDK installer for your platform and Python version from https://pypi.python.org/pypi/couchbase#files.

  3. Run the installer and follow any instructions given.

Installation by means of pip will not work on Windows.

Hello Couchbase

The code snippet below shows how the Python SDK may be used for some common operations.

FASTPATH: Couchbase Server 5.0 introduces Role-Based Access Control (RBAC), whereby bucket-access requires authentication by means of username and, typically, password. To access Couchbase Server 5.0-based clusters, you can continue using your existing SDK-version. Alternatively, you can upgrade to the most recent SDK-version, which provides an optimized authentication interface, for use with RBAC. See Authentication for information.

>>> from couchbase.bucket import Bucket
>>> cb = Bucket('couchbase://localhost/default')
>>> cb.upsert('u:king_arthur', {'name': 'Arthur',
...           'email': 'kingarthur@couchbase.com',
...           'interests': ['Holy Grail', 'African Swallows']})
OperationResult<RC=0x0, Key=u'u:king_arthur', CAS=0xb1da029b0000>
>>> cb.get('u:king_arthur').value
{u'interests': [u'Holy Grail', u'African Swallows'], u'name': u'Arthur', u'email': u'kingarthur@couchbase.com'}
>>> cb.n1ql_query('CREATE PRIMARY INDEX ON default').execute()
>>> from couchbase.n1ql import N1QLQuery
>>> row_iter = cb.n1ql_query(N1QLQuery('SELECT name FROM default WHERE ' +\
... '$1 IN interests', 'African Swallows'))
>>> for row in row_iter: print(row)
{u'name': u'Arthur'}


To connect to a Couchbase bucket, simply instantiate the couchbase.Bucket class, specifying any cluster node and the bucket name in the connection string.

from couchbase.bucket import Bucket
bucket = Bucket('couchbase://hostname-or-ip/bucket-name')

See Managing Connections Using the Python SDK with Couchbase Server for more connection options and details about the connection string.

Document Operations

Document operations, such as storing and retrieving documents, can be done using simple methods on the Bucket class such as Bucket.get and Bucket.upsert. Simply pass the key (and value, if applicable) to the relevant methods.

rv = bucket.get('document-id')
bucket.upsert('document-id', {'application': 'data'})

N1QL Queries

Couchbase N1QL queries are performed by creating a N1QLQuery object and passing that to the Bucket.n1ql_query() method:

from couchbase.n1ql import N1QLQuery
query = N1QLQuery("""SELECT airportname, city, country FROM `travel-sample` """
                  """WHERE type="airport" AND city=$my_city""", my_city="Reno")
for row in bucket.n1ql_query(query):

API Reference

The API reference is generated for each release and can be found at http://pythonhosted.org/couchbase. Most of the API documentation can also be accessed via pydoc.

Release Notes

Information on new features, fixes, known issues as well as information on how to install older release versions is in the release notes.

PyPy support

Because the Python SDK is written primarily in C using the CPython API, the official SDK will not work on PyPy.

An unofficial module, couchbase_ffi uses ffi rather than the CPython C API to implement the internals of the library, and may be used with pypy.


Couchbase welcomes community contributions to the Python SDK. The Python SDK source code is available on GitHub.