Couchbase Python Client Library (Official)
griels PYCBC-534: fix tests to work with real server
Various fixes for real-server tests so that the combination tests pass.

This comment initiates full pipeline testing (inc combination tests):


Change-Id: I2f813caf7dd9b0eaee310917da7074dd503e66b4
(cherry picked from commit fa07ebe35fa9129b491ddb75b9462daf0060e799)
Tested-by: Ellis Breen <>
Reviewed-by: Brett Lawson <>
Reviewed-by: Sergey Avseyev <>
Tested-by: Build Bot <>
Latest commit bd3bcbb Nov 29, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
acouchbase PYCBC-535: Fix 'object from __aiter__ that does not implement __anext__' Nov 6, 2018
couchbase PYCBC-534: fix tests to work with real server Dec 4, 2018
docs PYCBC-532: Analytics Deferred Queries for Python Nov 6, 2018
examples PYCBC-518: further lost span fixes Aug 17, 2018
gcouchbase PYCBC-504: rename 'async' to 'asynchronous' for python 3.7 Jul 4, 2018
jenkins PYCBC-548: Fix AnalyticsIngester docs. Nov 26, 2018
src PYCBC-532: Analytics Deferred Queries for Python Nov 6, 2018
txcouchbase PYCBC-550: Correct txcouchbase get_multi example Nov 26, 2018
.gitignore PYCBC-465: Add Snappy Compression Feature Feb 26, 2018
.tests.ini.travis Upgrade to new mock Jan 14, 2015
.travis.yml PYCBC-503: Update Travis APT source to point to up-to-date libcouchbase Jun 25, 2018
CMakeLists.txt PYCBC-523: add parameterized query support for analytics Oct 2, 2018 fix typo in contribution guide Sep 27, 2013
LICENSE Adding Apache License 2.0 Mar 22, 2013 Add __version__ (and generate it if necessary) Jun 25, 2013
README.rst PYCBC-462: End to end tracing Apr 13, 2018 couchbase_version: Warn and generate dummy version for bad tag Dec 9, 2015
dev_requirements.txt PYCBC-554: Update dependencies Nov 30, 2018
requirements.txt Move previous requirements.txt to dev_requirements Oct 27, 2015 PYCBC-554: Update dependencies Nov 30, 2018
tests.ini.sample PYCBC-535: Fix 'object from __aiter__ that does not implement __anext__' Nov 6, 2018


Couchbase Python Client

Client for Couchbase.


This is the documentation for the 2.x version of the client. This is mostly compatible with the older version. Please refer to the release12 branch for the older version.

Building and Installing

This only applies to building from source. If you are using a Windows installer then everything (other than the server) is already included. See below for windows snapshot releases.

Also note that these instructions apply to building from source. You can always get the latest supported release version from pypi.

If you have a recent version of pip, you may use the latest development version by issuing the following incantation

pip install git+git://



The following will compile the module locally; you can then test basic functionality including running the examples.

python build_ext --inplace

If your libcouchbase install is in an alternate location (for example, /opt/local/libcouchbase), you may add extra directives, like so

python build_ext --inplace \
    --library-dir /opt/local/libcouchbase/lib \
    --include-dir /opt/local/libcouchbase/include

If you wish to enable the experimental tracing feature, set the PYCBC_TRACING_ENABLE environment variable.

Or you can modify the environment CFLAGS and LDFLAGS variables.


If you do not intend to install this module, ensure you set the PYTHONPATH environment variable to this directory before running any scripts depending on it. Failing to do so may result in your script running against an older version of this module (if installed), or throwing an exception stating that the couchbase module could not be found.


python install


Authentication is handled differently depending on what version of Couchbase Server you are using:

Couchbase Server < 5.0

Each bucket can optionally have a password. You may omit the authenticator if you are only working with password-less buckets.

>>> from couchbase.cluster import Cluster, ClassicAuthenticator
>>> cluster = Cluster('couchbase://localhost')
>>> cluster.authenticate(ClassicAuthenticator(buckets={'bucket-name': 'password'}))
>>> bucket = cluster.open_bucket('bucket-name')

Couchbase Server >= 5.0

Role-Based Access Control (RBAC) provides discrete username and passwords for an application that allow fine-grained control. The authenticator is always required.

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

Here's an example code snippet which sets a key and then reads it

>>> bucket.upsert("key", "value")
OperationResult<RC=0x0, Key=key, CAS=0x31c0e3f3fc4b0000>
>>> res = bucket.get("key")
>>> res
ValueResult<RC=0x0, Key=key, Value=u'value', CAS=0x31c0e3f3fc4b0000, Flags=0x0>
>>> res.value

You can also use views

>>> resultset = bucket.query("beer", "brewery_beers", limit=5)
>>> resultset
View<Design=beer, View=brewery_beers, Query=Query:'limit=5', Rows Fetched=0>
>>> for row in resultset: print row.key
[u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-21a_ipa']
[u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-563_stout']
[u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-amendment_pale_ale']
[u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-bitter_american']

Twisted API

The Python client now has support for the Twisted async network framework. To use with Twisted, simply import txcouchbase.connection instead of couchbase.bucket

from twisted.internet import reactor
from txcouchbase.bucket import Bucket

cb = Bucket('couchbase://localhost/default')
def on_upsert(ret):
    print "Set key. Result", ret

def on_get(ret):
    print "Got key. Result", ret

cb.upsert("key", "value").addCallback(on_upsert)

# Output:
# Set key. Result OperationResult<RC=0x0, Key=key, CAS=0x9a78cf56c08c0500>
# Got key. Result ValueResult<RC=0x0, Key=key, Value=u'value', CAS=0x9a78cf56c08c0500, Flags=0x0>

The txcouchbase API is identical to the couchbase API, except that where the synchronous API will block until it receives a result, the async API will return a Deferred which will be called later with the result or an appropriate error.

GEvent API

from gcouchbase.bucket import Bucket

conn = Bucket('couchbase://localhost/default')
print conn.upsert("foo", "bar")
print conn.get("foo")

The API functions exactly like the normal Bucket API, except that the implementation is significantly different.

Asynchronous (Tulip) API

This module also supports Python 3.4/3.5 asynchronous I/O. To use this functionality, import the couchbase.experimental module (since this functionality is considered experimental) and then import the acouchbase module. The acouchbase module offers an API similar to the synchronous client:

import asyncio

import couchbase.experimental
from acouchbase.bucket import Bucket

async def write_and_read(key, value):
    cb = Bucket('couchbase://')
    await cb.connect()
    await cb.upsert(key, value)
    return await cb.get(key)

loop = asyncio.get_event_loop()
rv = loop.run_until_complete(write_and_read('foo', 'bar'))


PyPy is an alternative high performance Python implementation. Since PyPy does not work well with C extension modules, this module will not work directly. You may refer to the alternate implementation based on the cffi module:

Other Examples

There are other examples in the examples directory. To run them from the source tree, do something like

PYTHONPATH=$PWD ./examples/ -U couchbase://localhost/default

Building documentation

The documentation is using Sphinx and also needs the numpydoc Sphinx extension. In order for the documentation to build properly, the C extension must have been built, since there are embedded docstrings in there as well.

To build the documentation, go into the docs directory and run

make html

The HTML output can be found in docs/build/html/.

Alternatively, you can also build the documentation (after building the module itself) from the top-level directory:

python build_sphinx

Once built, the docs will be in in build/sphinx/html


For running the tests, you need the standard unittest module, shipped with Python. Additionally, the testresources package is required.

To run them, use either py.test, unittest or trial.

The tests need a running Couchbase instance. For this, a tests.ini file must be present, containing various connection parameters. An example of this file may be found in tests.ini.sample. You may copy this file to tests.ini and modify the values as needed.

The simplest way to run the tests is to declare a bucket_prefix in the tests.ini file and run the script to create them for you.


To run the tests:


Support & Additional Resources

If you found an issue, please file it in our JIRA. You can ask questions in our forums or in the #libcouchbase channel on freenode.

The official documentation can be consulted as well for general Couchbase concepts and offers a more didactic approach to using the SDK.


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