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

    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.

    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 BASH (MacOS 10.14 Mojave and older)
    $ echo 'export PATH="/usr/local/bin:"$PATH' >> ~/.bash_profile
    For TLS/SSL support - recommended

    Best practice is to use a secure connection. However, since some scenarios don’t require a secure connection, TLS support is recommended but not required.

    Connecting to Couchbase Capella requires TLS support.
    $ brew install openssl

    Install the latest Python SDK:

    $ sudo -H python3 -m pip install couchbase

    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.

    During first-time setup:

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

    For TLS/SSL support (recommended):

    Connecting to Couchbase Capella requires TLS support.
    $ sudo apt-get install libssl-dev

    First, make sure the requirements have been installed.

    Install the latest Python SDK:

    $ python3 -m pip install couchbase

    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.

    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 (recommended):

    Connecting to Couchbase Capella requires TLS support.
    $ 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 eeded 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. 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 --no-binary couchbase couchbase==3.3.0

    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.8 and 3.9.

    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.8 or 3.9):

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

    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 cmake 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 using Windows, and no wheel is available, see the alternate installlation methods on the Github README. The same process should work within the Anaconda/Miniconda platform.

    PyPy support

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