Couchbase Python SDK Release Notes and Archives

    Release notes, installation instructions, and download archive for the Couchbase Python Client.

    The Couchbase Python SDK 3.0 is a complete rewrite of the API, reducing the number of overloads to present a simplified surface area, and adding support for future Couchbase Server features like Collections and Scopes (available in Couchbase Server 6.5 & 6.6 as a developer preview).

    The 3.0 Python SDK introduces comprehensive PEP-484 style type annotations.


    Couchbase Python SDK bundles libcouchbase automatically, so no need to install it separately. You may need CMake to install, although the installer will attempt to download it from PyPI automatically.

    The Python SDK 3.0 requires Python 3, with Python 3.5 and above supported.

    Because the Python SDK is written primarily in C using the CPython API, the official SDK will not work on PyPy.


    You may install previous versions of the SDK using pip (after installing the required dependencies)

    $ python3 -m pip install git+

    where VERSION is the version you wish to install. For example, to install version 2.5.4:

    $ python3 -m pip install git+

    Currently the Python Client source distribution requires the OpenSSL headers and libraries that the Python client itself was built against to be installed prior to the client itself for TLS support to be provided. Additionally the installer relies on PEP517 which older versions of PIP do not support. If you experience issues installing it is advised to upgrade your PIP/setuptools installation as follows:

    $ python3 -m pip install --upgrade pip setuptools wheel

    Installing on Linux

    • Debian and Ubuntu

    • RHEL and CentOS

    During first-time setup:

    $ sudo apt-get install git-all python3-dev python3-pip python3-setuptools cmake build-essential

    For TLS/SSL support (optional):

    $ sudo apt-get install libssl-dev

    Now install the latest Python SDK:

    $ python3 -m pip install couchbase

    During first-time setup:

    $ sudo yum install gcc gcc-c++ python3-devel python3-pip cmake
    You may need to update your installed version of CMake. For example, by following the steps here.

    For TLS/SSL support (optional):

    $ sudo yum install openssl-devel

    Now install the latest Python SDK:

    $ python3 -m pip install couchbase
    RHEL/CentOS distributions may not provide the python3-pip package in the base repositories. It may be found in the EPEL repository.

    Installation on Mac OS X

    The following example uses the Python supplied by the Homebrew package manager and not the vendor-supplied Python which ships with OS X.

    To install the library on Mac OS X, first install Homebrew: Homebrew. Once Homebrew is configured:

    Later versions of Mac OS X break the python3 homebrew installer. Simple mitigating steps may be found here.
    $ brew update # get list of latest packages
    $ brew install python3
    $ brew install openssl # for TLS/SSL support - optional
    $ python3 -m pip install couchbase

    Installing on Microsoft Windows

    $ python3 -m pip install couchbase

    The standard Python distributions for Windows include OpenSSL DLLs, as PIP and the inbuilt ssl module require it for correct operation. The binary wheels for Windows are packaged as a binary wheel built against the relevant version OpenSSL (which is fixed per Windows version of Python).

    If you require a version without OpenSSL support, or that doesn’t have a suitable binary wheel on PyPi, follow the build instructions on the GitHub repo.

    Upgrading to 3.x

    Python SDK 3.n automatically bundles libcouchbase (downloading and building it if necessary), so no need to install it separately.

    Version 3.0.5 (4 September 2020)

    $ python3 -m pip install couchbase==3.0.5



    • PYCBC-1011: If tests.ini not in current dir, now uses base path of PYCBC distro.

    • PYCBC-1016: Reenabled non-hybrid build for CLion.

    Version 3.0.4 (11 August 2020)

    $ python3 -m pip install couchbase==3.0.4


    • PYCBC-915: Remove support for Python <3.5.

    • PYCBC-951: The MutateInOptions don’t have durability.

    • PYCBC-986: Expose and document 'condition' parameter used to create partial N1QL indices.

    • PYCBC-989: Add xattr flag to SD.upsert.

    • PYCBC-954: Can’t query in the cloud.

    • PYCBC-983: Make Conan/PyGithub deps contingent on build reqs, enable 3.5 support.

    • PYCBC-984: Some N1QL query settings may not get set.

    • PYCBC-987: ImportError: DLL load failed: The specified module could not be found. - SSL.

    • PYCBC-988: Update release notes generator.

    • PYCBC-994: Remove error_map test as fetching is now automatic

    • PYCBC-1001: "Could NOT find PythonLibs (missing: PYTHON_LIBRARIES)" causing PEP517 install error.

    • PYCBC-1002: Explicitly set adhoc to off with lcb_cmdquery_adhoc and prepared statements.


    • PYCBC-671: Add Amazon Linux 2 verification testing.

    • PYCBC-933: Review docs for update items, identify/file issues.

    • PYCBC-992: Pin LCB to 3.0.3

    • PYCBC-998: SSL install notes update.

    Version 3.0.3 (15 July 2020)

    $ python3 -m pip install couchbase==3.0.3


    Version 3.0.2 (14 July 2020)

    Version 3.0.2 is the third release of the 3.0 series, bringing enhancements and bug fixes over the last stable release.

    $ python3 -m pip install couchbase==3.0.2


    • PYCBC-920: Twisted api seeing lots of timeouts.

    • PYCBC-941: Build against correct OpenSSL version on Windows.

    • PYCBC-950: N1QL query connections remain open after completion.

    • PYCBC-970: Python SDK assumes docstrings are available.


    • PYCBC-885: FTS Doc for Python 3.0.

    • PYCBC-929: Document how to get encrypted connections to clusters.

    • PYCBC-591: Document analytics using the Python SDK at draft level.

    Version 3.0.1 (12 June 2020)

    Version 3.0.1 is the second release of the 3.0 series, bringing enhancements and bug fixes over the last stable release.

    $ python3 -m pip install couchbase==3.0.1


    Bug Fixes

    • PYCBC-714: Python SDK throwing SystemError.

    • PYCBC-833: get_all_replicas segfaults.

    • PYCBC-834: Intermittent segfault in collection.exists.

    • PYCBC-912: Generated docs need a second pass.

    • PYCBC-918: Version 3 needs access to bucket "default" to connect.

    • PYCBC-924: invoking type superconstructor on some platforms.

    • PYCBC-928: Bootstrap timing out on Centos.

    • PYCBC-930: Using cert_path= in ClusterOptions hit inner_cause='cert_path' is an invalid keyword argument for this function, C Source=(src/bucket.c,1047).

    • PYCBC-934: Some Query OptionBlocks not passing kwargs to constructor.

    • PYCBC-936: QueryScanConsistency object should be an Enum.

    • PYCBC-937: Rename CBAS to ANALYTICS/Analytics to match LCB/RFC.

    • PYCBC-939: Unpin some dev_requirements entries.

    Version 3.0.0 (1 May 2020)

    This is the first GA release of the third generation Python SDK.

    $ python3 -m pip install couchbase==3.0.0
    Whilst we have made our best efforts to update the API documentation to accurately reflect the functionality provided, there are still some known documentation issues to be resolved. We aim to fix these as soon as possible.

    Known issues

    • PYCBC-912 Generated docs need a second pass.

    • PYCBC-834 Intermittent segfault in collection.exists.

    • PYCBC-833 get_all_replicas segfaults.

    And an issue in libcouchbase that impacts upon the Python Client:

    • CCBC-128 Segfault in lcbtrace_span_add_tag_uint64.


    • PYCBC-816: Migrate txcouchbase to SDK3.

    • PYCBC-805: Provide async access to Cluster.

    • PYCBC-658: Provide txcouchbase support for durability.

    • PYCBC-826: Implement acouchbase for Windows.

    • PYCBC-622: Document/configure Git dependency.

    • PYCBC-673: Prefer locally bundled lcb include for installs.

    • PYCBC-681: Make OptionBlock arguments discoverable.

    • PYCBC-698: Fixed test failures against real servers.

    • PYCBC-711: Create AnalyticsIndexManager, fix analytics queries, with v3 tests.

    • PYCBC-719: The ViewIteratorTests all are skipping when they should not.

    • PYCBC-723: needs to be implemented.

    • PYCBC-732: QueryIndexManager interface work, plus fixes for failing tests.

    • PYCBC-746: Remove NodeManager from API.

    • PYCBC-747: Remove generic Manager API.

    • PYCBC-752: ViewIndexManager needs proper SDK3 interface.

    • PYCBC-754: Fix invalid named args in Collection.get.

    • PYCBC-771: Mark multi-operations as volatile until sdk-rfc done.

    • PYCBC-785: Expose ErrorContexts.

    • PYCBC-794: Implement Cluster.disconnect.

    • PYCBC-798: Ping is returning 'scope' instead of 'namespace'.

    • PYCBC-801: Reflect optional nature of parameters in OptionBlock constructors.

    • PYCBC-803: Reinstate non-hybrid (pure CMake) build.

    • PYCBC-815: Share lcb_INSTANCE objects between collections.

    • PYCBC-817: Collection get_and_touch, get_and_lock need to be SDK3-ized.

    • PYCBC-838: Client Durability support.

    • PYCBC-473: Add FTS Index Management.

    • PYCBC-691: Set up Combination Testing for SDK 3 - Server 5.5, 6.0, 6.5.

    • PYCBC-729: Add necessary build tools to the

    • PYCBC-777: Complete KV doc for GA.

    • PYCBC-779: Getting Started docs Tidy Up.

    • PYCBC-781: Managing Connections doc.

    • PYCBC-841: Update integration testing Jenkins node labels.

    • PYCBC-844: Convert integration tests to nightlies.

    • PYCBC-743: Mark all ErrorContexts as Uncommitted.

    • PYCBC-751: AnalyticsIndexes manager missing on Cluster.

    • PYCBC-775: Migrate collection attributes to use timedelta for durations.

    • PYCBC-744: Ensure precedence between named param and option block is described.

    • PYCBC-864: Provide asyncio access to Cluster, also analytics and search.

    • PYCBC-707: Sweep through tests, examine why some are skipped.

    • PYCBC-840: Add testing for 6.5 with DP enabled.

    • PYCBC-845: Nightlies need to build and test (against mock) on more platforms.

    • PYCBC-847: Consolidate exceptions into one place.

    • PYCBC-870: Testing on MacOS.

    • PYCBC-873: CMake: Skip PythonLibs search for Hybrid builds, remove -pthreads.

    • PYCBC-886: Expiry not properly returned or set.

    • PYCBC-895: Improve navigability/API docs for async, remove factories.

    • PYCBC-896: Remove unused code (unshared collection, v2 async code).


    • PYCBC-774: Proper implementation for Collection.get_all_replicas.

    • PYCBC-782: Fix durability_level on collection.remove.

    • PYCBC-789: N1QL query request to create index appears to fail.

    • PYCBC-792: Cluster.diagnostics always times out.

    • PYCBC-795: ViewManager needs to wrap http calls for proper exceptions.

    • PYCBC-799: Ensure v3 tests all pass on Jenkins against real servers.

    • PYCBC-800: Fix BucketMissingException when trying to connect to Cluster.

    • PYCBC-807: Correct CollectionManager docstrings.

    • PYCBC-808: Fix AnalyticsOptions code.

    • PYCBC-818: Collection.exists always returning true.

    • PYCBC-829: Collection.get_and_lock should not get and lock in 2 commands.

    • PYCBC-850: CBCollectionShared not passing through collection name.

    • PYCBC-855: ViewResult recurses infinitely on some platforms.

    • PYCBC-857: Address some missing error context types.

    • PYCBC-859: Bucket exception parsing broken by server message change.

    • PYCBC-756: Append, Prepend, Increment, Decrement need to move to BinaryCollection.

    • PYCBC-749: Remove additional overloads for query and search.

    • PYCBC-806: Various PEP8 formatting fixes.

    • PYCBC-809: PEP8/MyPy warning removal.

    • PYCBC-839: CreateCollection CollectionSpec must include MaxTTL.

    • PYCBC-760 Fixed Collection.exists implementation.

    • PYCBC-640 Implemented replica reads according to RFC.

    • PYCBC-768: Refactored durability params to prevent impossible combinations.

    • PYCBC-639: Example N1QL statements don’t seem to work in "Hello Couchbase" example.

    • PYCBC-667: Fixed Upsert Group fails with 'roles: value must be supplied'.

    • PYCBC-674: Fixed deprecation warnings from sdk2 when running sdk3.

    • PYCBC-675: Brough Result objects in line with RFC, removed unidiomatic interfaces.

    • PYCBC-694: Completed query implementation.

    • PYCBC-753: Collection APIs marked volatile.

    • PYCBC-763: Corrected MutateInResult.content_as implementation.

    • PYCBC-764: Delete or renamed remaining SDK2 references in main API: Renamed SDK2/sdk2 to Core/core where applicable. Removed classes & methods inapplicable to SDK3.

    • PYCBC-704: Implemented *CollectionOptions for Collection management API.

    • PYCBC-716: Tests should no longer try to do 6.5-specific tests against a 6.0 server.

    • PYCBC-686: Applied new naming convention for interfaces/protocols.

    • PYCBC-687: Support added for Python 3.8.

    • PYCBC-761: Added timeout to lookup_in operation.

    • PYCBC-784: Remove/move/mark "internal" Admin methods/class.

    • PYCBC-793: Cluster.bucket needs kwargs for the tests to work against the mock.

    • PYCBC-796: Move some tests on sdk2 to sdk3.

    • PYCBC-797: needs to respect the timeout in the options if any.

    • PYCBC-824: QueryResult has a few fields that are not implemented yet.

    • PYCBC-831: Cluster settings like compression, tracing, etc.. should be set at Cluster initialisation only.

    • PYCBC-832: Test issues with cluster and opening new buckets.

    • PYCBC-835: Diagnostics hangs on any server < 6.5.

    • PYCBC-854: ping() needs to be at the cluster level as well.

    • PYCBC-860: Don’t pass a bucket name for cluster connections by default.

    • PYCBC-863: iterable_wrapper failing for some async operations.

    • PYCBC-869: Cattrs library doesn’t work with python 3.5.2.

    • PYCBC-874: Do cluster ops on 6.5-DP.

    • PYCBC-875: ViewQuery segfaults in bindings.

    • PYCBC-878: Tx stuff seems to have broken imports recently.

    • PYCBC-881: Make (txcouchbase|acouchbase).cluster.Cluster.connect return an instance of the relevant class.

    • PYCBC-882: Fix dropped imports.

    • PYCBC-883: Some remaining exceptions not listed in Error Handling RFC.

    • PYCBC-898: Correct threshold naming for search and query.

    • PYCBC-899: Import error in search tests.

    • PYCBC-902: Add more coverage to integration tests.

    • PYCBC-903: Further improve Async API/docstrings.

    • PYCBC-905: Pip install fails for latest sdk commits on python 3.5.x.

    • PYCBC-908: Add some missing View result types.

    • PYCBC-897: Update 'long_description' settings to conform with PyPi.

    • PYCBC-910: Factor CBCollectionShared into CBCollectionBase.

    • PYCBC-911: Remove content_as_array as not in RFC.


    Numerous Alpha and Beta releases were made in the run-up to the 3.0 release, and although unsupported, the release notes and download links are retained for archive purposes here.

    Older Releases

    Although no longer supported, documentation for older releases continues to be available in our docs archive.