aiochclient

library2.7.0pypypi✓ verified 85d ago

Async HTTP ClickHouse client for Python 3.6+. Provides both high-level and low-level interfaces for querying ClickHouse databases over HTTP. Current version 2.6.0, maintained.

database http-networking

pip install aiochclient

github ↗package ↗

INSTALL

IMPORT

SIG · AIOCHCLIENT

aiochclient

databasepythonv2.7.0

Install

7.0s avg

Import

93ms

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.7.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

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.097s · 30.2MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 7.0s · import 0.088s · 32MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ChClient

✓ from aiochclient import ChClient

Standard import path.

Basic usage: create session, execute query, iterate rows.

import asyncio from aiochclient import ChClient from aiohttp import ClientSession async def main(): # No auth is default; for auth use headers or query params (see docs) url = 'http://localhost:8123' async with ClientSession(url, headers={'X-ClickHouse-User': 'default', 'X-ClickHouse-Key': ''}) as session: client = ChClient(session) rows = await client.execute('SELECT version()') for row in rows: print(row) asyncio.run(main())

Debug

Known issues

breakingFrom v2.0.x, aiohttp is no longer a mandatory dependency. You must install either aiochclient[aiohttp] or aiochclient[httpx] explicitly.

fix

Install with the desired extra, e.g., pip install aiochclient[aiohttp].

affects: >=2.0.0

breakingIn v2.3.0, authentication data is passed via headers instead of query parameters for security reasons. Old code using query params will break.

fix

Remove 'user' and 'password' from the URL query; set 'X-ClickHouse-User' and 'X-ClickHouse-Key' headers instead.

affects: >=2.3.0

deprecatedThe cchardet library is abandoned and will cause import errors. aiochclient v2.6.0 fixed this by making cchardet optional.

fix

Use pip install aiochclient[charset_normalizer] if you need charset detection, or remove cchardet from your dependencies.

affects: >=2.6.0

gotchaWhen using httpx client, responses are read by bytes. If you expect string results, you may need to decode explicitly.

fix

Use aiohttp client for automatic string decoding, or decode bytes manually.

affects: >=2.3.1

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'aiohttp'

aiohttp is not installed (aiochclient >=2.0.0 makes HTTP backends optional).

fix

pip install aiochclient[aiohttp]

aiochclient.exceptions.ClickHouseError: Code: 516, e.displayText() = DB::Exception: ... Authentication failed

Authentication is not passed correctly; since v2.3.0 headers are used, not query params.

fix

Set 'X-ClickHouse-User' and 'X-ClickHouse-Key' (or 'X-ClickHouse-Password') headers on the ClientSession.

AttributeError: module 'aiochclient' has no attribute 'ChClient'

Trying to import from wrong module or outdated install.

fix

from aiochclient import ChClient

TypeError: object ChClient can't be used in 'await' expression

Trying to await the client constructor or a non-awaitable method.

fix

Use client as a plain object; only query methods like execute() are awaitable.

Upgrade

Version history

2.7.0latest on PyPI · released Jun 4, 2026

Audit

Dependencies

aiohttpoptionalOptional HTTP client engine. One of aiohttp or httpx must be installed.

httpxoptionalOptional HTTP client engine. One of aiohttp or httpx must be installed.

Agent activity

62 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/maximdanilchenko/aiochclient ↗

packagehttps://pypi.org/project/aiochclient/ ↗