Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Couchbase Python client library (official)

Make async view classes function as mixins

This will allow better code reuse with N1QL

Change-Id: I05cf01f96a7c8e3981673310f670e97cfcca1675
Tested-by: Mark Nunberg <>
Reviewed-by: Volker Mische <>
latest commit ddbb4b6d1f
M. Nunberg mnunberg authored mnunberg committed


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

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


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

>>> from couchbase.bucket import Bucket as CouchbaseBucket
>>> c = CouchbaseBucket('couchbase://localhost/default')
>>> c
<couchbase.bucket.Bucket bucket=default, nodes=['localhost:8091'] at 0x105991cd0>
>>> c.upsert("key", "value")
OperationResult<RC=0x0, Key=key, CAS=0x31c0e3f3fc4b0000>
>>> res = c.get("key")
>>> res
ValueResult<RC=0x0, Key=key, Value=u'value', CAS=0x31c0e3f3fc4b0000, Flags=0x0>
>>> res.value

You can also use views

>>> from couchbase.bucket import Bucket as CouchbaseBucket
>>> c = CouchbaseBucket('couchbase://localhost/beer-sample')
>>> resultset = c.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.connection import Connection as TxCouchbase

cb = TxCouchbase('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.connection import GCouchbase
conn = GCouchbase('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.


`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. To build the documentation, go into the docs directory and run

make html

The HTML output can be found in docs/build/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:



If you found an issue, please file it in our JIRA. You may also ask in the #libcouchbase IRC channel at freenode. (which is where the author(s) of this module may be found).


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

Something went wrong with that request. Please try again.