Full Installation
- reference
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 may benefit from our Platform Help page.
Requirements
The Python SDK requires CPython 3.11 or later. See the Python Version Compatibility section for details on supported versions of Python.
Binary Wheels
Most installs need nothing beyond a supported Python and pip.
PyPI carries one stable-ABI (abi3) wheel per platform, and that one wheel works on every supported Python version from 3.11 up.
pip selects it automatically.
The wheel bundles the C++ core, Couchbase++, and statically links BoringSSL, so there is no compiler, CMake or SSL library to install.
Building from Source
When no wheel matches the platform, pip builds the SDK from its source distribution.
That build needs:
-
A C++ 17 compiler, such as GCC 8 or later.
-
CMake 3.19 or later. If CMake is not found, the installer downloads it from PyPI.
-
The OpenSSL headers and libraries, since a source build links against the system OpenSSL by default.
-
A
piprecent enough to support PEP 517. If the build fails early, upgradepip,setuptoolsandwheelfirst:$ python3 -m pip install --upgrade pip setuptools wheel
The build instructions on GitHub cover the build options, including linking BoringSSL instead of OpenSSL.
Dependencies
pip installs these alongside the SDK:
-
typing-extensions, on Python versions before 3.13. -
grpcio,protobuf,googleapis-common-protosandcertifi, whichcouchbase2://connections use.
The optional otel extra adds the OpenTelemetry API and SDK, as described in Metrics Reporting:
$ python3 -m pip install "couchbase[otel]"
Installation
-
macOS
-
Debian & Ubuntu
-
RHEL & CentOS
-
Windows
-
Conda
The steps below install Python with Homebrew and the SDK into a virtual environment. To manage several versions of Python, use pyenv instead of brew.
The Python SDK has a wheel for macOS covering supported versions of Python.
| The Python that ships with Xcode is often older than 3.11. Install a supported 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:
$ brew update
$ brew install python3
$ echo 'export PATH="/usr/local/bin:"$PATH' >> ~/.zshrc
$ source ~/.zshrc
Create a virtual environment, activate it, and install the latest Python SDK:
$ python3 -m venv .venv
$ source .venv/bin/activate
$ python -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, when building from source. 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.
Best practice is to use a Python virtual environment such as venv or pyenv to manage multiple versions of Python. See pyenv docs for details.
The Python SDK has a manylinux wheel covering supported versions of Python.
During first-time setup:
$ sudo apt-get install git-all python3-dev python3-pip python3-venv python3-setuptools build-essential
First, make sure the requirements have been installed.
Create a virtual environment, activate it, and install the latest Python SDK:
$ python3 -m venv .venv
$ source .venv/bin/activate
$ python -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, when building from source. Older versions of RHEL and CentOS 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, and if not then investigate the EPEL repository.
Best practice is to use a Python virtual environment such as venv or pyenv to manage multiple versions of Python. See pyenv docs for details.
The Python SDK has a manylinux wheel covering supported versions of Python.
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. |
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.
Create a virtual environment, activate it, and install the latest Python SDK:
$ python3 -m venv .venv
$ source .venv/bin/activate
$ python -m pip install 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. |
The Python SDK has a wheel for Windows covering supported versions of Python.
First, make sure the requirements have been installed.
Create a virtual environment, activate it, and install the latest Python SDK:
python -m venv .venv
.venv\Scripts\activate
python -m pip install couchbase
The Windows wheel statically links BoringSSL, so it does not depend on the OpenSSL DLLs that ship with Python.
| 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.12
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. |
Installing a Specific Version
You may install previous versions of the SDK using pip.
$ python3 -m pip install couchbase==VERSION
Where VERSION is the version you wish to install. For example, to install version 4.7.0:
$ python3 -m pip install couchbase==4.7.0
For more detailed installation instructions, see the full installation guide.