A newer version of this documentation is available.

View Latest

Install and Start Using the C (libcouchbase) SDK with Couchbase Server

    The Couchbase C SDK (libcouchbase) enables C and C++ programs to access a Couchbase cluster. The C SDK is also commonly used as a core dependency of SDKs written in other language to provide a common implementation and high performance.


    • Cross-Platform: Officially supported on Linux, Mac OS X, and Microsoft Windows (though it is also known to run on other platforms).

    • Key-Value (CRUD) operations (lcb_get3, lcb_store3, etc.)

    • N1QL query operations (lcb_n1ql_query)

    • Map Reduce (view) query operations (lcb_view_query)

    • Secure SSL connections (Couchbase Enterprise only)

    • Pluggable non-blocking event loops such as libevent, libev, and libuv- integrate with your own non-blocking application, or use lcb_wait in blocking code

    Note that SSL and N1QL features depend on server support. See Compatibility to see which server versions support which features.

    Platform support and installation

    The Couchbase C SDK can be installed via apt or yum repositories on Linux; homebrew on Mac OS X; and binary archives for Microsoft Windows. It may also be built from source on any of the platforms mentioned above, and more.

    Installing on Linux

    For installation on Linux, install the couchbase-release repository, and then install the libcouchbase packages. The following examples download and install couchbase-release repository, a C and C++ compiler, and the C SDK core (libcouchbase2-core), command line tools (libcouchbase2-bin), and the development tools (libcouchbase-devel [RPM] or libcouchbase-dev [DEB]).

    Debian and Ubuntu
    # Only needed during first-time setup:
    wget http://packages.couchbase.com/releases/couchbase-release/couchbase-release-1.0-6-amd64.deb
    sudo dpkg -i couchbase-release-1.0-6-amd64.deb
    # Will install or upgrade packages
    sudo apt-get update
    sudo apt-get install libcouchbase-dev libcouchbase2-bin build-essential

    Note that as of Couchbase Data Platform 6.0, couchbase-release (1.0.6) supports Debian 7, 8, and 9, and Ubuntu 12.04, 14.04, 16.04, and 18.04. If you wish to install a Couchbase SDK on another Ubuntu or Debian variation, follow these steps (but note that while newer releases may work, other platforms are not necessarily supported):

    Adding repo manually
    # Install Couchbase's GPG key
    sudo wget -O - http://packages.couchbase.com/ubuntu/couchbase.key | sudo apt-key add -
    # Adding Ubuntu 18.04 repo to apt/sources.list of 18.10 or 19.04
    echo "deb http://packages.couchbase.com/ubuntu bionic bionic/main" | sudo tee /etc/apt/sources.list.d/couchbase.list
    # To install or upgrade packages
    sudo apt-get update
    sudo apt-get install libcouchbase-dev libcouchbase2-bin build-essential
    RHEL and CentOS
    # Only needed during first-time setup:
    wget http://packages.couchbase.com/releases/couchbase-release/couchbase-release-1.0-8-x86_64.rpm
    sudo rpm -iv couchbase-release-1.0-8-x86_64.rpm
    # Will install or upgrade existing packages
    sudo yum install libcouchbase-devel libcouchbase2-bin gcc gcc-c++
    You should install the libcouchbase2-libevent or libcouchbase2-libev plugin in case your application will use more than 1024 file descriptors. The default select() based event loop only supports 1024 file descriptors.

    The Release Notes page covers installation in more detail, including how to add the appropriate version of the repo yourself.

    Installation on Mac OS X

    To install the library on Mac OS X, first install the de-facto package manager for OS X: homebrew. Once homebrew is configured:

    brew update # get list of latest packages
    brew install libcouchbase@2
    LCB 2.10 & Homebrew

    This will install libcouchbase 2 in keg-only mode — meaning it is installed to Cellar, but not symlinked in /usr/local. If you have LCB 3.0 also installed on your development machine, you can change the linked version to 2.10.6 with brew link:

    brew unlink libcouchbase
    brew link --force --overwrite libcouchbase@2

    And reverse this when you need to develop on LCB 3.0. See the Homebrew docs for more on brew link.

    Installation on Microsoft Windows

    Windows binary packages can be found as downloads for each version listed on the Release Notes and Archives page, linked from the table in each Release Note, and categorized by Visual Studio version. Included are the header files, release and debug variants of the DLLs and import libraries, and release and debug variants of the command line tools. Note that the C SDK does not have any preferred installation path, and it is up to you to determine where to place libcouchbase.dll.

    Be sure to select the proper package for the compiler and architecture your application is using.

    If there are no binaries available for your Visual Studio version, then using a binary from any other Visual Studio version is likely to work. Most of the issues related to mixing Visual Studio binary versions involve changing and incompatible C APIs or incompatible C Runtime (CRT) objects and functions. Since the Couchbase C SDK does not expose a C API, and since it does not directly expose any CRT functionality, it should be safe for use so long as your application can link to the library at compile-time. The windows runtime linker will ensure that each binary is using the appropriate version of the Visual C Runtime (MSVCRT.DLL).

    If for some reason you cannot use any of the prebuilt Windows binaries, you may install from source — see the next section:

    Installing from Source Code

    You may install the library from source either by downloading a source archive, or by checking out the git repository. Follow the instructions in the archive’s README for further instructions.

    Source archives can be found as a download for each version of the C SDK listed on the Release Notes and Archives page, linked from the table in each Release Note.

    Documentation and Examples

    Information on new features, fixes, known issues as well as information on how to install older release versions is available in the release notes.

    Hello Couchbase

    The simple example below (which requires version 2.5.6 or higher to function) can be integrated into an existing application, or added to a CLI skeleton to make a demo app. Error checking is omitted for brevity.

    #include <string.h>
    #include <libcouchbase/couchbase.h>
    static void
    opCallback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb) {
        fprintf(stderr, "%.*s: %s... ", (int)rb->nkey, rb->key, lcb_strcbtype(cbtype));
        if (rb->rc != LCB_SUCCESS) {
            fprintf(stderr, "%s\n", lcb_strerror(NULL, rb->rc));
        } else {
            fprintf(stderr, "OK");
            if (cbtype == LCB_CALLBACK_GET) {
                const lcb_RESPGET *rg = (const lcb_RESPGET *)rb;
                fprintf(stderr, "... Value: %.*s\n", (int)rg->nvalue, rg->value);
            } else {
                fprintf(stderr, "\n");
    int storeAndRetrieveKey()
        assert(lcb_version_g >= 0x020506 && "This example requires 2.5.6 or greater");
        lcb_t instance;
        struct lcb_create_st options;
        memset(&options, 0, sizeof options);
        options.version = 3;
        options.v.v3.connstr = "couchbase://localhost/bucketname";
        options.v.v3.username = "mark";
        options.v.v3.passwd = "s3cr3t";
        lcb_error_t rc = lcb_create(&instance, &options);
        lcb_install_callback3(instance, LCB_CALLBACK_GET, opCallback);
        lcb_install_callback3(instance, LCB_CALLBACK_STORE, opCallback);
        lcb_CMDSTORE scmd = { 0 };
        LCB_CMD_SET_KEY(&scmd, "key", 3);
        LCB_CMD_SET_VALUE(&scmd, "true", 4);
        scmd.operation = LCB_SET;
        lcb_store3(instance, NULL, &scmd);
        lcb_CMDGET gcmd = { 0 };
        LCB_CMD_SET_KEY(&gcmd, "key", 3);
        lcb_get3(instance, NULL, &gcmd);
        return 0;

    Scheduling, Blocking and non-blocking

    The library is designed to be non-blocking. As opposed to a blocking API where API calls themselves perform the operations and return results, the C SDK’s non-blocking API schedules the operation, with the result of the operation being passed to a callback which is invoked when ready. The readiness and completion of an operation will only happen when the library has had a chance to send the operation to the server and await a response from the network.

    Most operations in the library do not execute the operation immediately, but rather schedule it to be executed when it is possible to perform network I/O.

    The lcb_wait() function will instruct the library to send all scheduled operations to the cluster and await the results for those operations. As results become available, designated callbacks (specified using lcb_install_callback3()) are invoked with the results.

    If your application is built on top of an event loop (for example, libev) you can integrate the C SDK to perform its I/O within the context of your event loop, avoiding the need to block for I/O with lcb_wait().

    Library Handle and Server Connections

    Almost all operations within the library are done with a library handle of type lcb_t. The lcb_t is a handle representing a connection to a single bucket (though it is possible to access other buckets as well for certain operations).

    An lcb_t is created using the lcb_create() function. Once created the handle must be connected: lcb_connect() schedules the connection and lcb_wait waits for the connection to complete. Once lcb_wait returns, lcb_get_bootstrap_status may be used to determine if the connection completed successfully.

    Any Cluster nodes addresses passed in to establish (bootstrap) the connection should be for data (KV) nodes.

    Note: If you have an environment with port mapping, such as Couchbase Server and the SDK in separate containers under Kubernetes, see the multi-network configuration note under Managing Connections

    Once the handle has been successfully connected it may then be used for data access.

    When the library handle is no longer needed, it can be destroyed via lcb_destroy().

    API Reference

    The API reference is generated for each version. The API reference for version 2.10.7 is at http://docs.couchbase.com/sdk-api/couchbase-c-client-2.10.7