Couchbase PHP Installation Instructions and Archives

      Installation instructions, and download archive for the Couchbase PHP Client.

      For release notes, download links, and installation methods for earlier releases of the Couchbase PHP Client, see below.

      The Couchbase PHP SDK generally tracks PHP’s own supported versions, and recommends the most recent "Active Support" version, except as specified in our documentation and especially the release notes.

      As of April 2022, these versions are PHP 8.1 (Latest Active Support), 8.0 (Active Support), and 7.4 (Security Support).

      SDK Installation

      Installing on Mac and Linux systems

      Before installing the PHP SDK, the following dependencies must be installed. We recommend using OS specific utilities such as brew, apt-get, and similar package management utilities (depending on your environment):

      • cmake >= 3.20.0+

      • c++ compiler >= std_17

      • openssl >= 1.1+

      When installing OpenSSL via brew install on macOS, the command will not be sufficient to be able to build. The easiest way to fix this is to add the OPENSSL_ROOT_DIR env variable to your exports (e.g., .zshenv).

      $ export OPENSSL_ROOT_DIR=/usr/local/opt/openssl/

      If you have any issues setting this up, see the tips mentioned when you run brew info openssl.

      Now, install the Couchbase PHP SDK through your PHP distribution’s pecl command:

      $ pecl install couchbase

      Or install from the Couchbase repository:

      $ pecl install

      Then follow the post-installation steps.

      Alpine Linux

      Alpine Linux is very slim and uses musl libc and the apk package manager. As a result, the installation is a little different from other Unix-Like systems, and pecl equivalent packages are used instead.

      Using apk, you would install your preferred php version, install libcouchbase, and then install the equivalent pecl package for the version of php that you’re using.

      $ apk add php7
      $ apk add libcouchbase
      $ apk add php7-pecl-couchbase

      Then follow the post-installation steps.

      Installing on Microsoft Windows

      Currently there are no pre-built binaries for the Windows platform of PHP SDK 4.0.0. Instead, you will need to follow these steps to build an extension along with the PHP interpreter. This process will be simplified in a future 4.0.x release where the pre-compiled binaries will be published.

      Post Installation for All Platforms

      Once the PHP SDK has been installed, you need to specify that the PHP interpreter should load the Couchbase PHP SDK as an extension. To do this:

      1. Locate your php.ini file. This can be done using the command php --ini

        $ php --ini
        Configuration File (php.ini) Path: /usr/local/etc/php/7.4
        Loaded Configuration File:         /usr/local/etc/php/7.4/php.ini
        Scan for additional .ini files in: /usr/local/etc/php/7.4/conf.d
        Additional .ini files parsed:      (none)
      2. Insert a line in the php.ini file specifying the extension to be loaded; this should be in the [PHP] section. If you don’t know where that is, simply search for existing commented or uncommented extension= entries in the file.

        extension=json      ; not needed with PHP 8.0.0+
        On PHP version 7.2.0 and up, simply using the extension name is preferred. Previously, you might have used or couchbase.dll, depending on your platform.

      PHP Composer

      Once the PHP extension is installed, it may be used as any other PHP library through composer as posted at

      Ensure that you have installed Composer successfully — you can verify your installation with:

      $ composer --version
      Composer version 2.3.5 2022-04-13 16:43:00

      To add Couchbase to your project’s dependency list, simply update your composer.json file with the following dependencies:

      "require": {
        "ext-couchbase": "^4.0",
        "couchbase/couchbase": "^4.0"

      Run composer update to lock the change in the generated composer.lock file.

      Note on Extension Dependencies

      The Couchbase SDK depends on the JSON extension, which must be loaded before the SDK. However, it is already included on PHP 8.0.0+ as a core extension.

      Older Releases