A newer version of this documentation is available.

View Latest


The Python SDK enables you to interact with Couchbase Server from a Python application.

The Python SDK consists of a C extension and a Python layer written atop of it. The C extension utilizes the Couchbase C Client. The SDK consists of the following:

  • Couchbase Python Client

  • Developer guide (you’re reading it now!)

  • Python API reference

  • Sample applications (beer database)


To debug errors, you must be familiar with the architecture of the Python client to understand where problems might originate. The following components participate in typical operations:

  • Couchbase Server

    This is the server itself, which stores your data. Errors can happen here if your data does not exist, or if there are connectivity issues with one or more nodes in the server. While Couchbase Server is scalable and fault tolerant, there are naturally some conditions that cause failures (for example, if all nodes are unreachable).

  • libcouchbase (The C library)

    libcouchbase, our C client library, provides the underlying layer that handles network communication and protocol handling between a client and a Couchbase node. Network connectivity issues tend to happen here.

  • Python C Extension Layer

    The binding layer contains the C code that provides the bulk of the client. It interfaces with the C library component, handles passing of information between the C library and your application, performs input validation, and encoding and decoding of keys and values. The extension also provides the core support for Twisted and gevent integration.

  • Pure Python Layer

    The Python layer is written in, well, Python. Simple key-value operations are normally just dispatched to the extension layer. Most of the view operations are handled here as well, with the C binding layer just performing the lower-level network handling.


To take advantage of all features offered by Couchbase Server, you need to know what version of the client provides compatibility for the features you want to use. The following matrix shows which versions of the Python client support the major features of each version of Couchbase Server.

Note that some of the features are dependent on the underlying C library (libcouchbase).

Table 1. Couchbase Server abd SDK Supported Version Matrix
Server 1.8 Server 2.0 Server 2.5 Server 3.0 Server 4.0

Basic features

CRUD operations

Since 1.0

View Querying APIs

Since 1.0

Advanced features

Durability Requirements

Since 1.1.0/libcouchbase 2.3.0

Fast (CCCP) Bootstrapping

Not Supported

Since libcouchbase 2.3.0

SSL Connectivity

Not Supported

Since 2.0/libcouchbase 2.4.0

Bulk Operations

Since 1.0

Cross-SDK Data types

Not Supported

Since 2.0

N1QL Querying

Not Supported

Since 2.0.1

Administrative Features

Administrative API

Not Supported


Couchbase welcomes community contributions to the Python SDK. The Python SDK source code is available on GitHub.