ClickHouse Connect is the official Python driver for ClickHouse, providing a high-performance core database interface for Python applications, Pandas DataFrames, NumPy arrays, PyArrow tables, Polars DataFrames, and Apache Superset integration. It leverages the ClickHouse HTTP interface for maximum compatibility and is actively maintained with regular updates.
Install & Compatibility
Where this runs
tested against v1.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.960 runs
build_error
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 9.4s · import 0.501s · 586MB
485MB installed
● package 485MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_client
✓ from clickhouse_connect import get_client
✗ import clickhouse_connect
This quickstart demonstrates how to establish a connection to a ClickHouse server, create a table, insert data, and query it. It includes an example using the `query_df` method for Pandas DataFrames, which requires the `pandas` optional dependency. Credentials are loaded from environment variables for secure usage.
import clickhouse_connect
import os
host = os.environ.get('CH_HOST', 'localhost')
port = int(os.environ.get('CH_PORT', 8123)) # Use 8443 for TLS/Cloud
username = os.environ.get('CH_USER', 'default')
password = os.environ.get('CH_PASSWORD', '')
database = os.environ.get('CH_DB', 'default')
try:
client = clickhouse_connect.get_client(
host=host,
port=port,
username=username,
password=password,
database=database,
secure= (port == 8443) # Automatically use TLS for 8443
)
# Test connection
client.ping()
print(f"Successfully connected to ClickHouse at {host}:{port}")
# Create a table
client.command(
"CREATE TABLE IF NOT EXISTS my_test_table (",
" id UInt64,",
" name String,",
" value Float64",
") ENGINE MergeTree ORDER BY id"
)
print("Table 'my_test_table' created or already exists.")
# Insert data
data_to_insert = [
[1, 'Alpha', 100.1],
[2, 'Beta', 200.2],
[3, 'Gamma', 300.3]
]
client.insert('my_test_table', data_to_insert, column_names=['id', 'name', 'value'])
print("Data inserted into 'my_test_table'.")
# Query data
result = client.query('SELECT * FROM my_test_table ORDER BY id')
print("Query Results:")
for row in result.result_set:
print(row)
# Example with Pandas (requires 'pandas' extra)
try:
import pandas as pd
df = client.query_df('SELECT * FROM my_test_table')
print("\nPandas DataFrame Results:")
print(df)
except ImportError:
print("\nSkipping Pandas example: 'pandas' not installed. Install with `pip install clickhouse-connect[pandas]`")
finally:
if 'client' in locals():
client.close()
print("Connection closed.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe parameter `apply_server_timezone` in client and query methods was renamed to `tz_source` in v0.14.0.fixReplace `apply_server_timezone=True` (or similar) with `tz_source='auto'` or other valid options for timezone handling.
affects: >=0.14.0
breakingVersion 0.13.0 introduced a native write path for the `Variant` data type. Previously, values were stringified; now they are serialized using their native ClickHouse types client-side, which changes how `Variant` columns store data.fixReview insertion logic for `Variant` columns. Ensure that your application expects native type serialization. If using older ClickHouse server versions with `Variant`, compatibility issues may arise.
affects: >=0.13.0
breakingThe legacy executor-based asynchronous client (`AsyncClient(client=...)`) and related parameters (`executor_threads`, `executor`, `pool_mgr`) have been removed. The native aiohttp-based async client is now standard.fixMigrate to `clickhouse_connect.get_async_client()` or `create_async_client()`, which uses `aiohttp`. Ensure `aiohttp` is installed via `pip install clickhouse-connect[async]`.
affects: future 0.15.x releases (already removed in 0.15.0 changelog, listed as UNRELEASED breaking change prior to 0.15.0)
deprecatedPython 3.9 support is deprecated and will be removed in version 1.0. Python 3.8 is End-of-Life (EOL) and no longer officially tested or supported; wheels are not built for 3.8 AARCH64 versions.fixUpgrade to Python 3.10 or higher. The library officially tests against Python 3.10 through 3.14.
affects: Python 3.8 (unsupported), Python 3.9 (deprecated)
gotchaOptional dependencies (e.g., `numpy`, `pandas`, `pyarrow`, `polars`, `sqlalchemy`) are lazy-loaded. If you intend to use features relying on these, you must install them explicitly using the `[extra]` syntax (e.g., `pip install clickhouse-connect[pandas]`).fixAlways install necessary extras for features like Pandas DataFrame integration, even if the base `clickhouse-connect` package is already present.
affects: >=0.15.0
gotchaFor ClickHouse server versions 22.8 and 22.10+, there is an internal serialization format incompatibility for experimental JSON. Using multiple clients with mixed 22.8/22.9 and 22.10+ server versions will break if JSON support is enabled. Pandas 1.x support is also deprecated and will be dropped in 1.0.fixFor JSON, use separate Python interpreters for different ClickHouse server versions if mixed JSON usage is required. For Pandas, upgrade to Pandas 2.x or later.
affects: ClickHouse server versions 22.8/22.9 vs 22.10+, clickhouse-connect <1.0 for Pandas 1.x
gotchaWhen creating a DBAPI Connection or SQLAlchemy DSN, unrecognized keyword arguments or query parameters will now raise an exception instead of being passed as ClickHouse server settings. Server settings should be prefixed with `ch_`.fixPrefix any ClickHouse server-specific settings passed as keyword arguments or query parameters with `ch_` (e.g., `ch_max_rows_to_read=1000`).
affects: >=0.9.0
breakingInstalling `clickhouse-connect` in minimal environments (e.g., `alpine` Docker images) may fail if a C compiler is not present. The `lz4` dependency, required by `clickhouse-connect`, often needs to be built from source if a pre-built wheel is unavailable for the specific Python version and architecture, which necessitates a C compiler (like `gcc`).fixEnsure that build-essential packages are installed in your environment (e.g., `apk add build-base` for `alpine` Linux) before attempting to install `clickhouse-connect`, or use a Python base image that includes a C compiler.
affects: All versions of `clickhouse-connect` in environments lacking C compilers (e.g., `alpine` Linux), particularly for newer Python versions where `lz4` wheels might be unavailable.
Audit
Dependencies
certifirequiredRequired for secure connections.
urllib3requiredHTTP client library (>=1.26).
pytzrequiredTimezone handling.
zstandardrequiredZSTD compression support.
lz4requiredLZ4 compression support.
sqlalchemyoptionalSQLAlchemy Core dialect and Superset integration.
numpyoptionalIntegration with NumPy arrays and Pandas DataFrames.
pandasoptionalIntegration with Pandas DataFrames.
polarsoptionalIntegration with Polars DataFrames.
pyarrowoptionalIntegration with PyArrow tables and Arrow-backed Pandas DataFrames.
aiohttpoptionalRequired for the native asynchronous client.