---
id: chdb
version: "4.2.1"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# chdb — chDB is an in-process OLAP SQL Engine powered by ClickHouse

License: permissive · Maintenance: active · Downloads: 3.5M/mo

## What it is and what it does

chDB embeds ClickHouse's SQL OLAP engine directly into Python, letting you run SQL queries on local files and in-memory data without installing a separate database server. It supports multiple input/output formats (Parquet, CSV, JSON, Arrow, ORC, and 60+ others) and offers two APIs: a low-level SQL interface for direct queries, and a pandas-compatible API that compiles operations to optimized SQL.

The package is designed for analytics workflows where you need SQL performance on moderately large datasets without the operational overhead of a database server. It uses lazy evaluation to defer execution until results are needed, and minimizes data transfer between C++ and Python through memory views. Runtime dependencies include chdb-core, pandas, and pyarrow.

Use it for:

- Analyze Parquet or CSV files with SQL queries without loading them entirely into memory.
- Use familiar pandas syntax while getting ClickHouse SQL performance on large datasets.
- Execute SQL queries on multiple file formats and data sources with a unified interface.
- Build interactive data exploration workflows in Jupyter notebooks with lazy evaluation.
- Perform aggregations and groupby operations on large datasets using ClickHouse's multi-threaded engine.

## Worth the install?

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

chDB is an in-process SQL OLAP engine powered by ClickHouse that executes SQL queries on local data without requiring a separate ClickHouse server installation.

Yes. chDB is actively maintained, has no known vulnerabilities, low install friction, and a permissive license. It fills a clear niche for developers who want SQL analytics performance without database infrastructure. The pandas-compatible API lowers the learning curve for existing pandas users, and the SQL API provides escape hatches for advanced ClickHouse features.

## Install

pip install chdb
uv add chdb
poetry add chdb

## Installing chdb

Before you install: Low friction: pure Python wheel with three runtime dependencies (chdb-core, pandas, pyarrow). Active maintenance with a recent release (32 days old) and 2868 repository stars.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions; suitable for most projects.

Quickstart:

pip install chdb

import chdb
res = chdb.query('SELECT 1 as num', 'Pretty')
print(res)

# Or with pandas:
import pandas
df = pandas.DataFrame({'name': ['Alice', 'Bob'], 'age': [25, 30]})
print(df[df['age'] > 26])

Requires Python 3.9+; supports macOS and Linux (x86_64 and ARM64) only.

Verify before relying:

- Whether the pandas-compatible API is fully production-ready or still experimental.
- Performance characteristics and memory overhead when processing datasets larger than available RAM.
- Support status for Windows or other operating systems beyond macOS and Linux.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 3.5M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

in-process SQL OLAP engine, clickhouse python, sql analytics engine, local sql query, parquet csv json sql, embedded analytics database, python sql engine, olap-analytics, embedded-sql, pandas-compatible

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