---
id: couchbase
version: "4.6.2"
license: Apache License 2.0
license_treatment: permissive
maintenance: active
---

# couchbase — Python Client for Couchbase

License: permissive · Maintenance: active · Downloads: 859.8K/mo

## What it is and what it does

The Couchbase Python client is an official SDK for connecting Python applications to Couchbase Server, a distributed NoSQL database. It provides APIs for key-value operations, N1QL queries, full-text search, and analytics, with support for both synchronous and asynchronous patterns. The library is built on top of libcouchbase and requires a C++17 compiler and OpenSSL for compilation from source, though prebuilt wheels are available for Python 3.10, 3.11, and 3.12 on Windows, macOS, and Linux.

The package has been in active development since its first release and is currently in production-stable status. It depends only on typing-extensions for runtime and is actively maintained, with the latest release 57 days old. The library supports Python 3.7 and later, though wheels are provided for more recent versions. Installation typically requires system-level dependencies (compiler, CMake, OpenSSL) unless a prebuilt wheel is available for your platform.

Use it for:

- Building web applications that need fast document storage and retrieval with Couchbase as the backend database.
- Running N1QL queries against Couchbase clusters to aggregate or filter document data from Python code.
- Implementing real-time analytics pipelines that read from and write to Couchbase Server.
- Developing microservices that require distributed key-value caching and persistence.
- Migrating from other NoSQL databases to Couchbase while maintaining Python compatibility.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Python client library for connecting to and querying Couchbase Server, a NoSQL database, with support for key-value operations, queries, and document management.

Yes, with conditions. Install if you are already committed to Couchbase Server as your database and need a stable, officially-supported Python client. The permissive Apache License 2.0 and active maintenance are strong positives. However, be aware of one known vulnerability (PYSEC-2023-235) that needs verification for this release, and plan for medium install friction on platforms without prebuilt wheels. Not suitable if you need to avoid compiled C++ dependencies or are evaluating database options.

## Install

pip install couchbase
uv add couchbase
poetry add couchbase

## Installing couchbase

Before you install: Medium install friction due to compiled C++ dependencies (requires C++17 compiler support and OpenSSL). Prebuilt wheels available for Python 3.10, 3.11, 3.12 on Windows, macOS, and Linux, reducing friction on common platforms. Active maintenance with recent releases.

License in practice: Licensed under Apache License 2.0 (permissive), allowing commercial and private use with minimal restrictions. No copyleft obligations.

Quickstart:

pip install couchbase

from couchbase.cluster import Cluster
from couchbase.auth import PasswordAuthenticator

cluster = Cluster('couchbase://localhost', PasswordAuthenticator('user', 'password'))
bucket = cluster.bucket('bucket_name')
collection = bucket.default_collection()
result = collection.get('document_id')

Requires a running Couchbase Server instance. On source builds, requires C++17 compiler, CMake >= 3.18, OpenSSL development files, and Python development headers.

Verify before relying:

- Whether PYSEC-2023-235 affects the current 4.6.2 release or has been patched
- Specific performance characteristics or throughput limits under typical workloads
- Full feature parity between 4.x and older 3.x versions beyond stated compatibility

## Package facts

- License: Apache License 2.0 (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 859.8K/month (top 5,000 on PyPI)
- Known vulnerabilities: 1

## Tags

couchbase python client, nosql database driver, key-value store python, couchbase sdk, document database client, couchbase server connector, nosql, couchbase, database-driver

[View on SkillFed](https://skillfed.io/packages/couchbase) · [View on PyPI](https://pypi.org/project/couchbase/)