Install & Compatibility
Where this runs
tested against v0.2.11 · 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.95 runs
installs and imports cleanly · install 0.0s · import 1.098s · 24MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 1.090s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from clickhouse_driver import Client
errors
✓ from clickhouse_driver import errors
✗ from clickhouse_driver.exceptions import ...
Exceptions are directly available under `clickhouse_driver.errors`.
This quickstart demonstrates how to connect to a ClickHouse server using the `Client`, execute simple queries, create a table, insert data using parameterization, and retrieve data. It emphasizes proper connection management and basic CRUD operations. Environment variables are used for connection details for better security and flexibility.
import os
from clickhouse_driver import Client
# Ensure ClickHouse is running, e.g., with Docker:
# docker run -d --name clickhouse-server -p 8123:8123 -p 9000:9000 --ulimit nofile=262144:262144 yandex/clickhouse-server
host = os.environ.get('CLICKHOUSE_HOST', 'localhost')
port = int(os.environ.get('CLICKHOUSE_PORT', '9000')) # Default native protocol port
user = os.environ.get('CLICKHOUSE_USER', 'default')
password = os.environ.get('CLICKHOUSE_PASSWORD', '')
client = Client(host=host, port=port, user=user, password=password)
try:
# Execute a simple query
result = client.execute('SELECT 1 + 1 AS two')
print(f"Query result: {result}")
# Create a table and insert data
client.execute('DROP TABLE IF EXISTS test_data')
client.execute('CREATE TABLE test_data (id UInt64, name String) ENGINE = Memory')
data_to_insert = [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
client.execute('INSERT INTO test_data VALUES', data_to_insert)
print(f"Inserted {len(data_to_insert)} rows.")
# Select data
selected_data = client.execute('SELECT id, name FROM test_data ORDER BY id')
print(f"Selected data: {selected_data}")
finally:
client.disconnect()
print("Disconnected from ClickHouse.")
Debug
Known issues
breakingPython version support has changed significantly. Versions 0.2.0 dropped Python 2 support. Version 0.2.9 dropped support for Python 3.6, 3.7, and 3.8. The current minimum supported Python version is 3.9.fixEnsure your Python environment is 3.9 or higher. For older Python versions, use an older `clickhouse-driver` version (e.g., <0.2.9 for Python 3.8).
affects: >=0.2.0, >=0.2.9
breakingDefault connection parameters for `Client` changed in version 0.2.4. Specifically, `secure` now defaults to `False`, `port` defaults to `9000` (native protocol), and `compression` defaults to `False`. Previously, `secure` might have defaulted to `True` or different port values depending on prior library usage assumptions.fixExplicitly set `secure=True` if you require TLS/SSL. Always specify `port` if you are not using the default native protocol (9000) or HTTP protocol (8123, which is handled by a different client usually).
affects: >=0.2.4
gotchaThe `clickhouse-driver` client does not include built-in connection pooling. For applications requiring high concurrency or frequent connections, you will need to implement a connection pool manually or use an external library.fixImplement a connection pooling mechanism using libraries like `queue` or `DBUtils` in Python, or use an ORM/framework that provides connection pooling capabilities for database drivers.
affects: All versions
gotchaAlways use parameterization for inserting data or executing queries with user-provided values to prevent SQL injection vulnerabilities. Direct string formatting of queries is insecure.fixPass data as a list of tuples to `client.execute()` for `INSERT` statements, e.g., `client.execute('INSERT INTO my_table VALUES', [(1, 'a'), (2, 'b')])`. For `SELECT` or `UPDATE` with parameters, use the `%s` placeholder and pass a tuple/list for the parameters: `client.execute('SELECT * FROM users WHERE id = %s', (user_id,))`. affects: All versions
breakingThe `clickhouse-driver` client requires a running ClickHouse server to establish a connection. If the server is not accessible or not running at the specified host and port (defaulting to localhost:9000 for native protocol), connection attempts will fail.fixEnsure your ClickHouse server is running and configured to listen on the host and port that your client is attempting to connect to. Verify network connectivity and firewall rules. If connecting to a remote server, ensure the correct host and port are provided to the client.
affects: All versions
gotchaThe `clickhouse-driver` client requires a running ClickHouse server to establish a connection. A `ConnectionRefusedError` (Code: 210) typically indicates that the client could not connect to the specified host and port, likely because no ClickHouse server is listening or the network path is blocked.fixEnsure that a ClickHouse server is running and accessible from the client's environment on the specified host and port (default is `localhost:9000`). Verify firewall rules and network connectivity between the client and the ClickHouse server.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'clickhouse_driver'
The 'clickhouse-driver' library or a required internal module was not installed, incorrectly installed, or is not accessible in the current Python environment. This can also happen with specific sub-modules like 'clickhouse_driver.varint' if the installation is corrupted or incomplete, especially after an upgrade.
fixEnsure the library is correctly installed using pip: `pip install clickhouse-driver`. If a specific sub-module error persists, try reinstalling in a clean virtual environment or upgrading to the latest version: `pip install --upgrade clickhouse-driver`.
DB::Exception: Authentication failed (Code: 516)
The provided username, password, host, or port for connecting to the ClickHouse server is incorrect. This error can also occur due to incorrect user permissions, network restrictions, or if TLS is required but not configured (e.g., in ClickHouse Cloud where `secure=True` is often mandatory).
fixDouble-check the host, port (default `9000` for native TCP, `9440` for TLS), username, and password. Verify that the ClickHouse server is running and configured to accept connections on the specified TCP port. For secure connections, ensure `secure=True` is passed to the `Client` constructor. Consult ClickHouse server logs (`/var/log/clickhouse-server/clickhouse-server.log`) and `users.xml` for correct credentials and allowed host configurations.
clickhouse_driver.errors.ServerException: Code: 241. DB::Exception: Memory limit (total) exceeded
The ClickHouse server exhausted its allocated memory while attempting to execute a query or insert a batch of data, often due to very large or complex queries, or excessively large data batches being inserted.
fixOptimize your ClickHouse queries to be more memory-efficient. When inserting data, reduce the batch size to fewer rows per `client.execute()` call. On the server side, you may consider adjusting ClickHouse's `max_memory_usage` and other memory-related settings in `users.xml` or `config.xml`, but do so cautiously after optimizing queries.
DB::Exception: Cannot parse DateTime
The date or datetime string being inserted or queried does not conform to the formats expected by ClickHouse for `Date` or `DateTime` column types. ClickHouse primarily expects `YYYY-MM-DD HH:MM:SS` for `DateTime` and `YYYY-MM-DD` for `Date`, or a Unix timestamp. Timezone mismatches can also lead to this error.
fixEnsure that Python `datetime` objects passed to `clickhouse-driver` include timezone information (e.g., `datetime.now(timezone.utc)` for `DateTime64` columns with timezone). When inserting strings, format them strictly as `YYYY-MM-DD HH:MM:SS` (for DateTime) or `YYYY-MM-DD` (for Date). Alternatively, use ClickHouse's SQL parsing functions like `toDateTime()`, `parseDateTime()`, or `parseDateTimeBestEffort()` within your query to handle diverse input formats.
Upgrade
Version history
0.2.11latest on PyPI · released Jul 17, 2026
Audit
Dependencies
lz4requiredRequired for LZ4 compression support with ClickHouse native protocol.
pytzrequiredRequired for timezone handling when working with DateTime and DateTime64 types.
sixrequiredCompatibility layer, though less critical for modern Python versions supported.