Using the Python SDK

The Couchbase Python SDK library allows you to connect to a Couchbase cluster from Python. The Python SDK uses the high-performance C++ library, Couchbase++, to handle communicating to the cluster over the Couchbase binary protocol.

How to Engage

  • Join Discord and contribute.

    The Couchbase Discord server is a place where you can collaborate about all things Couchbase. Connect with others from the community, learn tips and tricks, and ask questions.

  • Ask and/or answer questions on the Python SDK Forums.

Installing the SDK


Best practice is to use a Python virtual environment such as venv or pyenv. Checkout:


The 4.0.2 release provides wheels for Windows, MacOS and Linux platforms (via manylinux) for Python 3.7 - 3.10.


If not on platform that has a binary wheel availble, the following is needed:

  • Python version 3.7 - 3.10

  • A C++ compiler supporting C++ 17

  • CMake (version >= 3.18)

  • Git (if not on a platform that offers wheels)

  • OpenSSL 1.1.1

  • If using the Twisted Framework and the txcouchbase API, Twisted >= 21.7.0 is required.


Some older linux platforms to not provide defaults (Python version, OpenSSL, C++ 17 support, etc.) that meet the Python SDK’s minimum requirements. Be sure to update to the minimum requirements prior to installing the SDK. See the dockerfiles folder in the Python SDK examples folder for references to working setups for various linux platforms.

After the above have been installed, pip install setuptools and wheel (see command below).

$ python3 -m pip install --upgrade pip setuptools wheel


$ python3 -m pip install couchbase


Connecting to a Couchbase cluster is as simple as creating a new Cluster instance to represent the Cluster you are using, and then using the bucket and collection commands against this to open a connection to open your specific bucket and collection. You are able to execute most operations immediately, and they will be queued until the connection is successfully established.

Here is a simple example of creating a Cluster instance, retrieving a document and using SQL++ (a.k.a. N1QL).

# needed for any cluster connection
from couchbase.auth import PasswordAuthenticator
from couchbase.cluster import Cluster
# options for a cluster and SQL++ (N1QL) queries
from couchbase.options import ClusterOptions, QueryOptions

# get a reference to our cluster
auth = PasswordAuthenticator('username', 'password')
cluster = Cluster.connect('couchbase://localhost', ClusterOptions(auth))

# get a reference to our bucket
cb = cluster.bucket('travel-sample')

# get a reference to the default collection
cb_coll = cb.default_collection()

# get a document
result = cb_coll.get('airline_10')
print(f'Document content: {result.content_as[dict]}')

# using SQL++ (a.k.a N1QL)
call_sign = 'CBS'
sql_query = 'SELECT VALUE name FROM `travel-sample` WHERE type = "airline" AND callsign = $1'
query_res = cluster.query(sql_query, QueryOptions(positional_parameters=[call_sign]))
for row in query_res:
    print(f'Found row: {row}')

Source Control

The source control is available on Github. Once you have cloned the repository, you may contribute changes through our gerrit server. For more details see


The Couchbase Python SDK is licensed under the Apache License 2.0.

See LICENSE for further details.