Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Couchbase Python client library (official)

PYCBC-229: mapkey single: remove [] in docs

Change-Id: I86dcfba25be69ab917be57d91665b9b3e751fe80
Reviewed-by: Matt Ingenthron <>
Tested-by: Mark Nunberg <>
latest commit bd9c4e2653
M. Nunberg mnunberg authored
Octocat-spinner-32 couchbase lockmode_t: Contention time may be equal April 08, 2014
Octocat-spinner-32 docs PYCBC-229: mapkey single: remove [] in docs April 14, 2014
Octocat-spinner-32 examples --batch/-N parameter to benchmark scripts January 28, 2014
Octocat-spinner-32 gcouchbase PYCBC-207: Support gevent 1.0 December 06, 2013
Octocat-spinner-32 src PYCBC-236: Handle row population outside of _fetch() March 07, 2014
Octocat-spinner-32 txcouchbase txcouchbase: Invoke ready_w() on connection loss February 03, 2014
Octocat-spinner-32 Run tests with Travis CI October 30, 2013
Octocat-spinner-32 .gitignore Move tests as subpackages October 16, 2013
Octocat-spinner-32 .tests.ini.travis Run tests with Travis CI October 30, 2013
Octocat-spinner-32 .travis.yml Updated travis to notify Mark rather than all of sdk_dev. November 20, 2013
Octocat-spinner-32 fix typo in contribution guide September 27, 2013
Octocat-spinner-32 LICENSE Adding Apache License 2.0 March 22, 2013
Octocat-spinner-32 Add __version__ (and generate it if necessary) June 25, 2013
Octocat-spinner-32 README.rst Remove 'TxCouchbase' class December 18, 2013
Octocat-spinner-32 PYCBC-220: Check explicitly that we're a git repo February 03, 2014
Octocat-spinner-32 requirements.txt Add testresources to requirements.txt October 18, 2013
Octocat-spinner-32 PYCBC-213: Add interfaces for lcb_cntl January 08, 2014
Octocat-spinner-32 Fix setup_tests script October 23, 2013
Octocat-spinner-32 tests.ini.sample Add proper mock URL for tests.ini October 30, 2013

Couchbase Python Client

Client for Couchbase.

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



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.

Windows Snapshots

A list of recent snapshot builds for Windows may be found here <>.

You can always get release binaries from PyPi (as above).


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

>>> from couchbase import Couchbase
>>> c = Couchbase.connect(bucket='default')
>>> c
<couchbase.connection.Connection bucket=default, nodes=[''] at 0xb21a50>
>>> c.set("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 import Couchbase
>>> c = Couchbase.connect(bucket='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.Couchbase

from twisted.internet import reactor
from txcouchbase.connection import Connection as TxCouchbase

cb = TxCouchbase(bucket='default')
def on_set(ret):
    print "Set key. Result", ret

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

cb.set("key", "value").addCallback(on_set)

# 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

The experimental_gevent_support constructor flag has now been removed. Instead, you can import the gcouchbase.connection package and use the GConnection class like so:

from gcouchbase.connection import GCouchbase
conn = GCouchbase(bucket='default')
print conn.set("foo", "bar")
print conn.get("foo")

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

Note that the new GCouchbase class does not use the same implementation as the experimental support featured in 1.1.0

Other Examples

There are other examples in the examples directory.

Building documentaion

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.