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, libcouchbase, which it uses for performance and reliability.
    Owing to the evolution of the Python language, API, and compiler over time, we support an optimal subset of Python platforms. Please see the Compatibility page for details.


    First, you will need to install libcouchbase.

    See https://github.com/couchbase/couchbase-python-client/blob/release25/README.rst#prerequisites to see the minimum version you will require. The latest patch release of libcouchbase 2.10 should always be fine with the latest Python 2.5 SDK.

    Install the latest compatible version of libcouchbase, following the instructions here. Note that the Windows installation handles this automatically.

    The Couchbase Python SDK 2.5 will run any any version of Python above 2.7 or 3.5 (Python 3.x only on Windows — with 3.6 and above strongly recommended, in order to ensure libcouchbase and the compiled C bindings are automatically installed via Python wheel, rather than requiring manual installation/compilation).

    Other prerequisites will depend upon your Operating System platform.

    Once libcouchbase is installed, please follow the instructions specific to your platform, below:

    Installing on Linux

    Debian and Ubuntu
    # Only needed during first-time setup:
    sudo apt-get install build-essential python-dev python-pip
    sudo -H pip install couchbase

    In most cases you’ll wish to install the Python 3 versions: python3-dev python3-pip. And then:

    sudo python3 -m pip install couchbase
    RHEL and CentOS
    # Only needed during first-time setup:
    sudo yum install gcc gcc-c++ python-devel python-pip
    sudo -H 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.

    In most cases you’ll wish to install the Python 3 versions: python3-devel python3-pip. And then:

    sudo python3 -m pip install couchbase

    Installing on Mac OS X

    As with the Linux installation, first install libcouchbase (LCB) following the instructions here. For 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@2
    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.

    The libcouchbase and python installations can both be combined, adding LCB to the brew install step for the homebrew version of Python, before installing the Python SDK with pip:

    brew install libcouchbase@2 python
    pip install couchbase

    See the LCB installation pages if you have more complex requirements. Please note that unless libcouchbase 2 is the first version in include/link search paths (see hints on non-tap install on this page), Python client 2.x will not build correctly via pip. You can explicilty link to these by installing using setup.py --include-dir <include_dir> --library-dir <library-dir> mentioned in the README.MD file on GitHub, however.

    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.

    pip install couchbase

    Hello Couchbase

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

    from couchbase.cluster import Cluster
    from couchbase.cluster import PasswordAuthenticator
    cluster = Cluster('couchbase://localhost')
    authenticator = PasswordAuthenticator('username', 'password')
    cb = cluster.open_bucket('bucket-name')
    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>
    # {u'interests': [u'Holy Grail', u'African Swallows'], u'name': u'Arthur', u'email': u'kingarthur@couchbase.com'}
    ## The CREATE PRIMARY INDEX step is only needed the first time you run this script
    cb.n1ql_query('CREATE PRIMARY INDEX ON bucket-name').execute()
    from couchbase.n1ql import N1QLQuery
    row_iter = cb.n1ql_query(N1QLQuery('SELECT name FROM bucket-name WHERE ' +\
    '$1 IN interests', 'African Swallows'))
    for row in row_iter: print(row)
    # {u'name': u'Arthur'}


    To connect to a Couchbase bucket, you must use Couchbase Role-Based Access Control (RBAC). This is fully described in the section Authorization. An authenticator, containing username and password, should be defined, and then passed to the cluster. Following successful authentication, the bucket can be opened.

    from couchbase.cluster import Cluster
    from couchbase.cluster import PasswordAuthenticator
    cluster = Cluster('couchbase://localhost')
    authenticator = PasswordAuthenticator('username', 'password')
    bucket = cluster.open_bucket('bucket-name')

    Once defined, the authenticator can be passed to other clusters, as appropriate.

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

    Any Cluster nodes addresses passed in to establish (bootstrap) the connection should be for data (KV) nodes.

    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 linked from the release notes for your version of the Python SDK. The latest version’s API reference can be found here. 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.