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.

    The Couchbase Python SDK 3.0 is a complete rewrite of the API, reducing the number of overloads to present a simplified surface area, and adding support for future Couchbase Server features like Collections and Scopes (available in Couchbase Server 6.5 as a developer preview). The 3.0 Python SDK introduces comprehensive PEP-484 style type annotations.


    Couchbase Python SDK bundles libcouchbase automatically, so no need to install it separately. You may need cmake to install, although the installer will attempt to download it from PyPI automatically.

    The Python SDK 3.0 requires Python 3, with Python 3.5 and above supported.

    Currently the Python Client requires the OpenSSL headers and libraries that the Python client itself was built against to be installed prior to the client itself. Better packaging for OpenSSL support is currently being developed.

    Installing on Linux

    Debian and Ubuntu
    # Only needed during first-time setup:
    sudo apt-get install git-all python3-dev python3-pip python3-setuptools cmake build-essential
    # for TLS/SSL support (optional)
    sudo apt-get install libssl-dev
    sudo pip3 install couchbase
    RHEL and CentOS
    # Only needed during first-time setup:
    sudo yum install gcc gcc-c++ python-devel python-pip cmake
    # for TLS/SSL support (optional)
    sudo yum install openssl-devel
    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 python
    brew install openssl # for TLS/SSL support - optional
    pip3 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

    pip install couchbase
    Because the Windows client is packaged as binary wheel, it currently is compiled without OpenSSL support, to allow it to be run without OpenSSL. We are working on providing OpenSSL support for Windows shortly — it is possible to build and run against an OpenSSL compiled for Windows manually given the correct version of the OpenSSL headers and libraries are visible to the compiler, and the OpenSSL dynamic libraries are in the PATH at runtime.

    Hello Couchbase

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

    from couchbase.cluster import Cluster, ClusterOptions
    from couchbase_core.cluster import PasswordAuthenticator
    cluster = Cluster('couchbase://localhost', ClusterOptions(PasswordAuthenticator('username', 'password')))
    cb = cluster.bucket('bucket-name')
    cb_coll = cb.default_collection()
                   {'name': 'Arthur', 'email': '', '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''}
    ## The CREATE PRIMARY INDEX step is only needed the first time you run this script
    from couchbase.cluster import QueryOptions
    row_iter = cluster.query('SELECT name FROM bucket-name WHERE $1 IN interests', QueryOptions(positional_parameters=['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, ClusterOptions
    from couchbase_core.cluster import PasswordAuthenticator
    cluster = Cluster('couchbase://localhost', ClusterOptions(PasswordAuthenticator('username', 'password')))
    bucket = cluster.bucket('bucket-name')
    coll = bucket.default_collection()

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

    See Managing Connections 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 = coll.get('document-id')
    coll.upsert('document-id', {'application': 'data'})

    N1QL Queries

    Couchbase N1QL queries are performed by running the Cluster.query method.

    from couchbase.cluster import QueryOptions
    query_result = cluster.query("""SELECT airportname, city, country FROM `travel-sample` """
                                 """WHERE type="airport" AND city=$my_city""",
                                 QueryOptions(named_parameters={'my_city': "Reno"}))
    for row in query_result:

    Additional Resources

    The API reference is generated for each release and the latest can be found here. Older API references are linked from their respective sections in the Release Notes. Most of the API documentation can also be accessed via pydoc.

    The Migrating from SDK2 to 3 page highlights the main differences to be aware of when migrating your code.

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

    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.

    Please let us know if you require a PyPy-compatible version of the SDK.