Couchbase Python SDK Installation

Installation instructions for the Couchbase Python Client.

This page covers installation of the SDK. A quick start guide in our Getting Started Guide should work for most users — and for anyone in a hurry to try out the SDK and our Hello World program, that page is usually the best place to get started — but more detailed installation instructions are provided here on this page for every supported platform. This guide assumes you have some familiarity with development using Python — if you are evaluating the SDK as a software architect, tester, or other non-Python role, you will benefit from our Platform Help page.

The Couchbase SDK 3.x API (used in the Python SDK 3.0 - 4.0) is a complete rewrite of the API, reducing the number of overloads to present a simplified surface area, and adding support for Couchbase Server features like Collections and Scopes (available from Couchbase Server 7.0).

3.x Python SDK introduced comprehensive PEP-484 style type annotations.

Requirements

Couchbase Python SDK bundles Couchbase++ automatically, so no need to install it separately. You may need CMake (a version >= 3.18) to install, although the installer will attempt to download it from PyPI automatically.

The Python SDK 4.x requires Python 3, with versions 3.7 - 3.10 supported. See the Compatibility section for details.

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. 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

Installation

macOS
Debian & Ubuntu
RHEL & CentOS
Windows
Conda

Best practice is to use a Python virtual environment such as venv or pyenv to manage multible versions of Python, but in cases where this is not practicable follow the brew steps below, and also modify your $PATH as shown.

As of the 4.0.1 release of the Python SDK, wheels are available for Python 3.7 - 3.10.

There can be a problem when using the Python (3.8.2) that ships with Xcode on Catalina. It is advised to install Python via pyenv (see the Python SDK Github README for further details on pyenv installation), Homebrew, or python.org

To install the library on Mac OS, first install Homebrew.

Later versions of Mac OS can break the python3 homebrew installer. Simple mitigating steps may be found here.

The following example uses the Python supplied by the Homebrew package manager and not the vendor-supplied Python which ships with Mac OS. Once Homebrew is configured:

Get a list of the latest packages

$ brew update

Install compatible Python 3

$ brew install python3

For ZSH (MacOS 10.15 Catalina and newer)

$ echo 'export PATH="/usr/local/bin:"$PATH' >> ~/.zshrc

For TLS/SSL support - required for Python SDK 4.x

$ brew install openssl@1.1

Install the latest Python SDK:

$ sudo -H python3 -m pip install couchbase

This SDK runs on top of the C++ core, Couchbase++, which requires a C++ 17 compiler, such as GCC 8.0, or more recent versions. Older versions of Debian and Ubuntu ship with an older version of GCC.

While workarounds are available for installing a newer build chain, some may not be within your company’s policy, so also take a look at container options — such as the unofficial Docker builds provided in the Python SDK 4.x examples folder here, which can at least be used as a reference to a known working set-up.

Check that you have a new enough release of Python (3.7 - 3.10).

Best practice is to use a Python virtual environment such as venv or pyenv to manage multible versions of Python. See pyenv docs for details.

As of the 4.0.2 release of the Python SDK, manylinux wheels are available for Python 3.7 - 3.10.

During first-time setup:

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

For TLS/SSL support (required for Python SDK 4.x):

$ sudo apt-get install libssl-dev

First, make sure the requirements have been installed.

Install the latest Python SDK:

$ python3 -m pip install couchbase

This SDK runs on top of the C++ core, Couchbase++, which requires a C++ 17 compiler, such as GCC 8.0, or more recent versions. Older versions of Debian and Ubuntu ship with an older version of GCC.

Workarounds are available for installing a newer build chain with EPEL, but this may not be within your company’s policy, so also take a look at container options — such as the unofficial Docker builds provided in the Python SDK 4.x examples folder here, which can at least be used as a reference to a known working set-up.

Check that you have a new enough release of Python (3.7 - 3.10), and if not then investigate the EPEL repository.

Best practice is to use a Python virtual environment such as venv or pyenv to manage multible versions of Python. See pyenv docs for details.

As of the 4.0.2 release of the Python SDK, manylinux wheels are available for Python 3.7 - 3.10.

During first-time setup:

$ sudo yum install gcc gcc-c++ python3-devel python3-pip

You may need to update your installed version of CMake. For example, by following the steps here.

For TLS/SSL support (required for Python SDK 4.x):

$ sudo yum install openssl-devel

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

First, make sure the requirements have been installed.

Install the latest Python SDK:

$ python3 -m pip install couchbase

Note, the OpenSSL version needed for TLS 1.3 (mandated for secure connection to Couchbase Capella) is openssl 1.1.1. This is newer than the one available in CentOS 7, and updated your OS’s libraries is beyond the scope of this documentation — but this can be installed through the already-mentioned EPEL repository. Once openssl (and other dependencies) are updated, an already-installed Couchbase Python SDK can be re-installed to use the libraries with:

$ python3 -m pip install --force-reinstall --no-cache couchbase

Download and install Python from python.org. Best practice is to use a Python virtual environment such as venv or pyenv.

Checkout the pyenv-win project to manage multiple versions of Python.

Wheels are available on Windows for Python 3.7 - 3.10.

First, make sure the requirements have been installed.

Commands assume user is working within a virtual environment.

Install the latest Python SDK (if using Python 3.7 - 3.10):

python -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 OpenSSL.

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

To use the SDK within the Anaconda / Miniconda platform, make sure the prerequisites for the desired Operating System are met:

git-all python3-dev python3-pip python3-setuptools build-essential

In the Anaconda Prompt, create a new environment:

conda create -n test_env python=3.9

Activate the environment:

conda activate test_env

Install the SDK:

python -m pip install couchbase

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

PyPy support

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