Registry / database / kafka-python

kafka-python

JSON →
library3.0.11pypypi✓ verified 25d ago

kafka-python is a pure Python client for Apache Kafka, designed to function much like the official Java client with a set of Pythonic interfaces for producing, consuming, and administering Kafka topics. It is actively maintained with frequent releases and supports Kafka brokers from version 0.8.0 up to 4.0 and beyond due to backward compatibility of the Kafka protocol. The current latest stable release is 2.3.1, though PyPI may list 2.3.0 as the newest packaged version.

pip install kafka-python
INSTALL
IMPORT
SIG · KAFKA-PYTHON
K
kafka-python
databasepythonv3.0.11
Install
2.5s avg
Import
488ms
Disk
55MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.0.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
musl
glibc
py 3.10
1/2 runs
✓ 2.6s
py 3.11
1/2 runs
✓ 2.35s
py 3.12
1/2 runs
✓ 2.3s
py 3.13
1/2 runs
✓ 2.3s
py 3.9
1/2 runs
✓ 3s
55MB installed
● package 55MB
Code
Verified usage

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

KafkaProducer
from kafka import KafkaProducer
KafkaConsumer
from kafka import KafkaConsumer
KafkaAdminClient
from kafka import KafkaAdminClient
from kafka.admin import KafkaAdminClient
While `kafka.admin` exists, the class `KafkaAdminClient` is typically imported directly from the top-level `kafka` package for convenience.
TopicPartition
from kafka import TopicPartition

This quickstart demonstrates how to set up a basic Kafka producer to send JSON messages to a topic and a consumer to read them. It highlights common configurations like `bootstrap_servers`, `value_serializer`/`value_deserializer`, `group_id`, and `auto_offset_reset`. Ensure a Kafka broker is running and accessible (e.g., at `localhost:9092`) and the target topic exists.

import os from kafka import KafkaProducer, KafkaConsumer import json import time # Configuration KAFKA_BOOTSTRAP_SERVERS = os.environ.get('KAFKA_BOOTSTRAP_SERVERS', 'localhost:9092') KAFKA_TOPIC = os.environ.get('KAFKA_TOPIC', 'my_test_topic') # --- Producer Example --- def produce_messages(): producer = KafkaProducer( bootstrap_servers=[KAFKA_BOOTSTRAP_SERVERS], value_serializer=lambda v: json.dumps(v).encode('utf-8') ) print(f"Producing messages to topic: {KAFKA_TOPIC}") for i in range(5): message = {'number': i, 'timestamp': time.time()} future = producer.send(KAFKA_TOPIC, message) try: record_metadata = future.get(timeout=10) print(f"Sent: {message} to partition {record_metadata.partition} offset {record_metadata.offset}") except Exception as e: print(f"Error sending message: {e}") producer.flush() # Ensure all messages are sent producer.close() print("Producer finished.") # --- Consumer Example --- def consume_messages(): consumer = KafkaConsumer( KAFKA_TOPIC, bootstrap_servers=[KAFKA_BOOTSTRAP_SERVERS], auto_offset_reset='earliest', # Start reading from the beginning of the topic if no committed offset enable_auto_commit=True, # Auto-commit offsets periodically group_id='my_python_group', # Required for auto-assignment and offset commits value_deserializer=lambda x: json.loads(x.decode('utf-8')) ) print(f"Consuming messages from topic: {KAFKA_TOPIC}") try: for message in consumer: # message value and key are deserialized print(f"Received: topic={message.topic}, partition={message.partition}, offset={message.offset}, key={message.key}, value={message.value}") except KeyboardInterrupt: print("Consumer interrupted.") finally: consumer.close() print("Consumer closed.") if __name__ == '__main__': # Make sure a Kafka broker is running at KAFKA_BOOTSTRAP_SERVERS (e.g., localhost:9092) # And the topic 'my_test_topic' exists (or let Kafka create it if configured) import threading # Run producer in a separate thread producer_thread = threading.Thread(target=produce_messages) producer_thread.start() # Give producer a moment to start and send some messages time.sleep(2) # Run consumer in the main thread (or another thread, but be mindful of thread-safety) consume_messages() producer_thread.join()
Debug
Known issues
breakingPython 2 support was officially dropped with `kafka-python` release 2.3.x. Users on Python 2 must use an older version of the library.
fix
Upgrade to Python 3.8+ or pin `kafka-python` to a version compatible with Python 2.x (e.g., < 2.3.0).
affects: < 2.3.0
gotchaThe `KafkaConsumer` class is *not* thread-safe. While `KafkaProducer` can be shared across threads, `KafkaConsumer` instances should not. For concurrent consumption, it's recommended to use multiprocessing or a separate `KafkaConsumer` instance per thread with proper synchronization.
fix
Use separate `KafkaConsumer` instances for each thread or process, or manage concurrency via multiprocessing.
affects: All versions
gotchaFor high-throughput applications, inefficient serialization (e.g., plain JSON) can become a bottleneck. Using more efficient formats like Avro or Protobuf with appropriate `key_serializer` and `value_serializer` functions is recommended.
fix
Implement custom `key_serializer` and `value_deserializer` functions using libraries like Avro or Protobuf for better performance and schema enforcement.
affects: All versions
gotchaRelying solely on `enable_auto_commit=True` can lead to message duplication or loss in case of consumer crashes, as offsets might be committed before messages are fully processed.
fix
Set `enable_auto_commit=False` and manually commit offsets using `consumer.commit()` after successful message processing to ensure exactly-once or at-least-once processing semantics.
affects: All versions
gotchaFor Kafka brokers version 0.11 and above, `kafka-python` uses a new message protocol that requires `crc32c` for checksum validation. The pure Python implementation is significantly slower.
fix
Install the `crc32c` package (e.g., `pip install 'kafka-python[crc32c]'`) for optimized native code, especially in high-throughput scenarios.
affects: All versions with Kafka brokers >= 0.11
gotcha`KafkaAdminClient` was historically marked as an unstable interface and, while improved, changes to its internal protocol tuple returns have occurred. Users should be mindful of potential interface adjustments in minor releases.
fix
Refer to release notes for `KafkaAdminClient` changes, and consider thorough testing if using advanced admin features. It's generally more stable in recent 2.x releases.
affects: < 2.3.0
Errors
Common errors & fixes
kafka.errors.NoBrokersAvailable: NoBrokersAvailable
The Kafka client cannot establish a connection with the specified bootstrap servers, often due to the Kafka broker being down, incorrect host/port configuration, network issues (firewall, DNS), or client-broker version incompatibility.
fix
Verify that Kafka brokers are running and accessible from the client, check network connectivity and firewall rules, ensure `bootstrap_servers` is configured with correct 'host:port' pairs, and confirm client/broker version compatibility (sometimes by explicitly setting `api_version`).
kafka.errors.OffsetOutOfRangeError
A Kafka consumer attempts to fetch messages from an offset that no longer exists in the broker's log, typically because old messages have been deleted due to retention policies or the consumer's committed offset is stale.
fix
Configure the `auto_offset_reset` parameter in `KafkaConsumer` to either 'earliest' (to start consuming from the beginning of the available log) or 'latest' (to start from the newest messages) to handle out-of-range offsets gracefully.
kafka.errors.AuthenticationFailedError: Authentication failed for user ...
The Kafka client is unable to authenticate with the broker, often due to incorrect SASL configuration parameters (e.g., `sasl_plain_username`, `sasl_plain_password`, `sasl_mechanism`) or an improperly configured Kerberos setup if GSSAPI is used.
fix
Double-check the `security_protocol`, `sasl_mechanism`, `sasl_plain_username`, and `sasl_plain_password` in your Kafka client configuration, ensuring they match the broker's security settings and that credentials are correct. For Kerberos, confirm the client machine has a valid Kerberos ticket and configuration.
kafka.errors.TimeoutException
A Kafka client (producer or consumer) operation, such as sending a message, fetching metadata, or committing offsets, failed to complete within the configured timeout period, often due to network instability, an overloaded Kafka broker, or leader election issues.
fix
Increase `request_timeout_ms` and `delivery_timeout_ms` in your client configuration, verify network connectivity between the client and Kafka brokers, monitor broker health and load, and ensure that all topic partitions have an active leader.
Upgrade
Version history
3.0.11latest on PyPI · released Aug 16, 2026
Audit
Dependencies
crc32coptionalHighly recommended for optimized CRC32c calculation with Kafka 0.11+ brokers, as the pure Python implementation is slow.
lz4requiredFor LZ4 compression/decompression support.
python-snappyrequiredFor Snappy compression/decompression support. Requires the native snappy library.
zstandardrequiredFor ZSTD compression/decompression support.
Agent activity
37 hits · last 30 days
node
34
Resources