Getting Started with the Python SDK

The Python client library provides fast and reliable access to documents stored inside your Couchbase Server cluster. It learns about your cluster topology automatically, so you never need to take your application down for configuration changes when your cluster expands.

With built in support for working with JSON in the Python client, using Couchbase Server 2.0 you have new ways to index and query data stored in the cluster. Just load our sample beer dataset and query them depending on your taste!

If you've already gotten started with the Couchbase SDK, see the quick links section below for downloads, API reference, and source code

Step 0: Get a Server

Get & Install Couchbase Server. Come back here when you're done.

Step 1: Get a Client Library


Step 1.0: Get libcouchbase

Windows users may skip this step as the C client library is bundled with the distribution.

Since the Python extension builds on the 2.1 version of the Couchbase C SDK you will need to get it. The C SDK downloads and instructions are here.  Be sure to install the header files, which are frequently in a -dev or -devel package, depending on your Operating System.

Note if you have an earlier version of the Couchbase C SDK, remove it before you install the new C SDK.

Now we're ready to install the Python SDK. Before we continue, ensure you have the minimum requirements needed for installation.


    Common Requirements
  • Python version 2.6 or greater (Python 3.x is supported as well). You can use
    python -V

    to output your Python version

  • Unix/Linux Requirements

    The following requirments are only needed if using on a Unix-type system where the extension will be built upon installation. Windows users should use the provided installer which contains pre-built binaries which already include the necessary dependencies.

    • libcouchbase 2.1.0 or greater together with its development files
    • A C Compiler
    • Python development files, which may be installed as follows
      • For RPM EL5 based distributions (e.g. RHEL 5.x, CentOS 5.x), assuming your Python 2.6 package is called python26
        sudo yum groupinstall "Development Tools" # For a C compiler
        sudo yum install python26-devel
      • For RPM EL6 based distributions (e.g RHEL 6.x, CentOS 6.x)
        sudo yum groupinstall "Development Tools" # For a C compiler
        sudo yum install python-devel
      • For Debian-based systems (including Ubuntu)
        sudo apt-get install build-essential # for a C compiler
        sudo apt-get install python-dev

    Step 1.1-A: Installing using pip

    You can use pip to install using

    pip install couchbase

    Step 1.1-B: Downloading Manually

    You can download an appropriate source or binary distribution for your platform by going to the Couchbase Python Package on Python's PyPi package index.

    If using a Windows installer, just double click on the exe and follow the steps. If using a source distribution, the normal process of

    tar xf couchbase-1.2.0.tar.gz
    cd couchbase-1.2.0
    python install


    Step 2: Try it out!


    Once the Couchbase Python Client Library has been installed, it's easy to get started.  Create a new Python file and add your import statements, or you can just follow along in the python shell.

    #!/usr/bin/env python
    from couchbase import Couchbase

    Creating a Couchbase Client Instance

    To create a Couchbase client instance, call the connect method with the host, port, username, password and bucket name.

    cb = Couchbase.connect(bucket='default',  host='localhost')

    Replace localhost with the hostname or IP of a cluster node, if your cluster does not have a node on the same host as the client.

    The default Couchbase Server installation creates a bucket named "default" without a password, which in this case is blank.  If you created an authenticated bucket, you should specify those values in place of the default settings above. 

    The construction of a Connection instance does require some overhead as the cluster topology is discovered, so as a best practice you should retain the client object for multiple requests. Note that the Connection object is thread-safe out of the box.

    CRUD Operations

    The primary CRUD API used by the Python Client is relatively straightforward. You create and update documents by supplying a key and value. You retrieve or remove documents by supplying a key.  For example, consider the JSON document that you'll find in the "beer-sample" bucket that's available when you install Couchbase Server and setup your cluster.  The key "new_holland_brewing_company-sundog" is associated with the beer document below.

        "brewery_id": "new_holland_brewing_company", 
        "category": "North American Ale", 
        "updated": "2010-07-22 20:00:20", 
        "name": "Sundog", 
        "upc": 0, 
        "srm": 0.0, 
        "style": "American-Style Amber/Red Ale", 
        "abv": 5.25, 
        "type": "beer", 
        "ibu": 0.0, 
        "description": "Sundog is an amber ale as deep as the copper glow of a Lake Michigan sunset. Its biscuit malt give Sundog a toasty character and a subtle malty sweetness. Sundog brings out the best in grilled foods, caramelized onions, nutty cheese, barbecue, or your favorite pizza."

    Note that credentials and bucket selection change to use the beer sample database.  If you do not have that sample database loaded, you may add it through Settings -> Sample Buckets. This will replace the previously created connection.

    cb = Couchbase.connect(bucket='beer-sample')

    To retrieve this document, you simply call the get method of the bucket.  The get method returns the Result of the object.

    Getting Documents

    result = cb.get('new_holland_brewing_company-sundog')

    If you print out the result, you will see the value along with some metadata:

    print result

    Which outputs:

    ValueResult<RC=0x0, Key=new_holland_brewing_company-sundog, Value={u'brewery_id': u'new_holland_brewing_company', u'category': u'North American Ale', u'updated': u'2010-07-22 20:00:20', u'name': u'Sundog', u'upc': 0, u'srm': 0.0, u'style': u'American-Style Amber/Red Ale', u'abv': 5.25, u'type': u'beer', u'ibu': 0.0, u'description': u'Sundog is an amber ale as deep as the copper glow of a Lake Michigan sunset. Its biscuit malt give Sundog a toasty character and a subtle malty sweetness. Sundog brings out the best in grilled foods, caramelized onions, nutty cheese, barbecue, or your favorite pizza.'}, CAS=0x66ce536e72dc0000, Flags=0x0>
    You can access the actual value by using the Result's object value property. We will use the pprint module (in the standard library) to give us a nice representation:
    from pprint import pprint
    pprint(result.value, indent=4)

    Which outputs:

    {   u'abv': 5.25,
        u'brewery_id': u'new_holland_brewing_company',
        u'category': u'North American Ale',
        u'description': u'Sundog is an amber ale as deep as the copper glow of a Lake Michigan sunset. Its biscuit malt give Sundog a toasty character and a subtle malty sweetness. Sundog brings out the best in grilled foods, caramelized onions, nutty cheese, barbecue, or your favorite pizza.',
        u'ibu': 0.0,
        u'name': u'Sundog',
        u'srm': 0.0,
        u'style': u'American-Style Amber/Red Ale',
        u'type': u'beer',
        u'upc': 0,
        u'updated': u'2010-07-22 20:00:20'}

    Storing Documents

    Documents are typically stored in JSON format, which is the default storage format of the client. As such, it will convert most native Python types to their JSON equivalent. Of course, you're not forced to store items as JSON - but storing items as JSON allows them to be indexed by map-reduce queries (see below)

    To add a JSON document, first create a dictionary.

    new_beer = {
       "name": "Old Yankee Ale",
       "abv": 5.00,
       "ibu": 0,
       "srm": 0,
       "upc": 0,
       "type": "beer",
       "brewery_id": "cottrell_brewing_co",
       "updated": "2012-08-30 20:00:20",
       "description": ".A medium-bodied Amber Ale",
       "style": "American-Style Amber",
       "category": "North American Ale"

    For a key, we'll concatenate the brewery name in lower case, followed by a dash, followed by the beer name. We'll also normalize the name by replacing spaces with underscore and making it all lowercase. By doing so, we can directly retrieve documents by key (not just through views, which will be covered later) since we can directly determine the key name.

    key = "{0}-{1}".format(
            new_beer['name'].replace(' ', '_').lower())
    # key is "cottrell_brewing_co-old_yankee_ale"

    With this new key, the JSON document may easily be stored.

    result = cb.set(key, new_beer)

    The set method will replace a key if it exists or add it if it does not, and will serialize its value to JSON by default. There are also individual add and replace methods.  The return value is a common Result object indicating status and other metadata, including its CAS -- a value indicating the Document's current version.

    print result
    OperationResult<RC=0x0, Key=cottrell_brewing_co-old_yankee_ale, Value=None, CAS=0x888b2ffcd1f00100>


    You may also remove the document by calling delete with the key:



    Storing Documents to Other Formats

    While the above example demonstrated how to store a Python dict as a document, you can use other datatypes as well. The Python library offers built-in support for storing to utf-8pickle, and byte (raw) formats. Specifying the format parameter instructs the library in what format your data will be stored. This can be handy if you need to store objects which don't need to be JSON (like byte strings) or objects which cannot be represented as JSON (like python sets).

    A full discussion and listing of storage formats and acceptable input types can be found in the API reference and the manual.

    cb.set("pickled_object", object(), format=couchbase.FMT_PICKLE)
    #OperationResult<RC=0x0, Key=pickled_object, Value=None, CAS=0x9bfa85d952b40200>
    #ValueResult<RC=0x0, Key=pickled_object, Value=<object object at 0x10042b0b0>, CAS=0x9bfa85d952b40200, Flags=0x1>
    cb.set("foo", b"\x01\x02\x00\x03", format=couchbase.FMT_BYTES)
    #OperationResult<RC=0x0, Key=foo, Value=None, CAS=0x4971c2ad3db60200>
    #ValueResult<RC=0x0, Key=foo, Value='\x01\x02\x00\x03', CAS=0x4971c2ad3db60200, Flags=0x2>


    Working with Views

    Map/Reduce Views are used to create queryable, secondary indexes in Couchbase Server.  The primary index for documents is the key you use when performing the standard CRUD methods described above.  See the view documentation for more information on writing views. 

    For this example, a by_name view in a beer design document will be queried.  This view simply checks whether a document is a beer and has a name.  If it does, it emits the beer's name into the index.  This view will allow for beers to be queried for by name.  For example, it's now possible to ask the question "What beers start with A?"

    function (doc, meta) {
      if (doc.type && doc.type == "beer" && {    
         emit(, null);


    Querying a view through the Python client is performed through the query method.

    rows = cb.query("beer", "by_name")
    The query method returns an iterator which yields ViewRow objects.
    for row in rows:
        print "Beer name is \"%s\". Its document is '%s'" % (row.key, row.docid)
    Finally, the view results can be modified by specifying keyword arguments when first calling the view method.
    rows = cb.query("beer", "by_name", limit=5, key="Sundog")


    Which then outputs:

    Beer name is "Sundog". Its document is 'new_holland_brewing_company-sundog'


    Then Learn More:

    The full getting started guide will cover additional getting started information. From there, move on to the tutorial, which will show how to build a full application on Couchbase Server with a JSON dataset, sample views, and modifying data.

    Quick Reference