---
id: clickhouse-driver
version: "0.2.11"
license: MIT
license_treatment: permissive
maintenance: active
---

# clickhouse-driver — Python driver with native interface for ClickHouse

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

## What it is and what it does

Clickhouse-driver is a native TCP client library for ClickHouse, the columnar analytics database. It provides two interfaces: a direct Client class for executing queries and retrieving results, and a DB API 2.0 compliant connection interface for applications expecting standard Python database semantics. The driver handles ClickHouse's native protocol directly rather than HTTP, supporting features like compression, TLS encryption, query settings, external data, and block-by-block result streaming. It includes comprehensive type support for ClickHouse's data types (integers, floats, dates, strings, arrays, tuples, maps, JSON, and more) and can work with multiple hosts.

The package depends on pytz and tzlocal for timezone handling, which is essential for ClickHouse's DateTime and DateTime64 types. It is actively maintained, supports Python 3.9 through 3.14, and has been in development since 2017. The library is positioned for developers building analytics applications, data pipelines, or tools that need to query ClickHouse clusters from Python.

Use it for:

- Execute analytical queries against ClickHouse and retrieve results in a Python application.
- Build ETL pipelines that insert bulk data into ClickHouse tables using parameterized queries.
- Integrate ClickHouse as a backend for a web application using the DB API 2.0 interface.
- Stream large result sets block-by-block to avoid loading entire datasets into memory.
- Query ClickHouse with TLS encryption and compression for secure, efficient network communication.

## Worth the install?

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

A native TCP driver for ClickHouse that executes queries and returns results, supporting both a direct client interface and Python DB API 2.0 specification.

Yes. The package is actively maintained, has no known vulnerabilities, supports modern Python versions, and provides both low-level and DB API interfaces suitable for different use cases. Medium install friction is typical for compiled drivers and poses no practical barrier. MIT licensing imposes no restrictions. Install if you need to query ClickHouse from Python.

## Install

pip install clickhouse-driver
uv add clickhouse-driver
poetry add clickhouse-driver

## Installing clickhouse-driver

Before you install: Medium install friction due to compiled wheels across multiple architectures and Python versions (3.9–3.14). Active maintenance with a recent release 28 days ago and ongoing repository activity suggests reliable support.

License in practice: MIT license permits use in commercial and proprietary projects with minimal restrictions; attribution is required but no copyleft obligations apply.

Quickstart:

pip install clickhouse-driver

from clickhouse_driver import Client
client = Client('localhost')
result = client.execute('SELECT 1')
print(result)

ClickHouse server must be running and accessible at the specified host.

Verify before relying:

- Whether NumPy array support requires an additional optional dependency or is built-in.
- Default port and connection parameters for the Client.
- Support for asynchronous operations (description references aioch wrapper but does not detail native async support).

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 16.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

clickhouse database driver, clickhouse python client, clickhouse tcp connection, clickhouse query execution, clickhouse db api, analytics database python, clickhouse native interface, clickhouse, analytics-database, tcp-protocol

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