Amazon Kinesis Client Library for Python

3.1.3 verified Fri May 01 auth: no python

Python interface for the Amazon Kinesis Client Library (KCL) MultiLangDaemon, enabling Python applications to process Kinesis streams using the KCL's multi-language protocol. Current version 3.1.3 (October 2025), with major version 3 introducing breaking changes from v2 (e.g., mandatory dual-stack endpoint support, removed checkpoint manager customizations). The library wraps Java KCL via a subprocess (MultiLangDaemon). Releases follow the upstream KCL Java library cadence.

pip install amazon-kclpy

Common errors

error java.lang.UnsupportedClassVersionError: software/amazon/kinesis/multilang/config/ConfigurationUtils has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 55.0 ↓

cause Java version mismatch: KCL v3 requires JDK 11+ (class version 61 = Java 17), but older JDK (<= 55 = Java 11) is installed.

fix

Install JDK 17 or later, or ensure JAVA_HOME points to JDK >= 11. Check: java -version Install: sudo apt install openjdk-17-jre

error ImportError: cannot import name 'Checkpointer' from 'amazon_kclpy.kcl' ↓

cause The internal API symbol 'Checkpointer' was removed in KCL v3; the class is no longer directly exposed.

fix

Use the high-level KCLProcess API instead: from amazon_kclpy import kcl; kcl.KCLProcess(processor).run(). Do not import Checkpointer directly.

Warnings

breaking KCL v3 removed the ability to customize checkpoint managers and requires dual-stack endpoint support (IPv6). Applications using custom checkpoint managers must migrate to KCL v3's default behavior or use KCL v2.x. ↓

fix Remove any custom CheckpointManager implementations. If dual-stack endpoints are unavailable, stay on KCL v2.x.

gotcha The library requires Java (JDK 8 or 11+) to be installed and on PATH. The MultiLangDaemon is a Java subprocess. Without Java, the application will fail with 'java: command not found'. ↓

fix Install JDK (8, 11, or 17) and ensure java is in PATH. On Ubuntu: sudo apt install openjdk-11-jre On macOS: brew install openjdk@11

deprecated KCL v2.x is in maintenance mode; no new features will be added. Users should migrate to v3.x. ↓

fix Upgrade to amazon-kclpy >=3.0.0 and update your record processor to match the v3 API (no custom checkpoint managers).

gotcha The pip package 'amazon-kclpy' is often confused with 'awskcl' (a community fork). The official AWS KCL Python package is 'amazon-kclpy'. ↓

fix Ensure you install amazon-kclpy, not awskcl. Correct: pip install amazon-kclpy Wrong: pip install awskcl

Imports

Checkpointer
wrong
```
from amazon_kclpy.kcl import Checkpointer
```
correct
```
from amazon_kclpy import kcl
```
Checkpointer is not directly exposed; use kcl.Checkpointer via the module.
KCLProcess
wrong
```
from amazon_kclpy import KCLProcess
```
correct
```
from amazon_kclpy import kcl
```
KCLProcess is actually amazon_kclpy.kcl.KCLProcess; the top-level package does not export it.

Quickstart

Basic KCL record processor that prints records and checkpoints.

import os
from amazon_kclpy import kcl

class SampleRecordProcessor(kcl.RecordProcessorBase):
    def initialize(self, input_stream):
        pass
    def process_records(self, records, checkpointer):
        for record in records:
            print(record.data.decode('utf-8'))
        checkpointer.checkpoint()
    def shutdown(self, checkpointer, reason):
        checkpointer.checkpoint()

if __name__ == '__main__':
    kcl.KCLProcess(SampleRecordProcessor()).run()