Registry / aws / amazon-kclpy

amazon-kclpy

library3.1.3pypypi✓ verified 48d ago

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.

aws data

pip install amazon-kclpy

github ↗package ↗homepage ↗

Install & Compatibility

Where this runs

tested against v3.1.3 · 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.95 runs

installs and imports cleanly · install 0.0s · import 0.020s · 85.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 14.6s · import 0.016s · 86MB

83MB installed

● package 83MB

Code

Verified usage

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

Checkpointer

✓ from amazon_kclpy import kcl

✗ from amazon_kclpy.kcl import Checkpointer

Checkpointer is not directly exposed; use kcl.Checkpointer via the module.

KCLProcess

✓ from amazon_kclpy import kcl

✗ from amazon_kclpy import KCLProcess

KCLProcess is actually amazon_kclpy.kcl.KCLProcess; the top-level package does not export it.

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()

Debug

Known issues

breakingKCL 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.

affects: >=3.0.0

gotchaThe 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

affects: all

deprecatedKCL 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).

affects: >=2.0.0, <3.0.0

gotchaThe 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

affects: all

Errors

Common errors & fixes

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

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

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

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.

Upgrade

Version history

3.1.3latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

82 hits · last 30 days

node

mj12bot

ahrefsbot

bytedance

amazonbot

Resources

githubhttps://github.com/awslabs/amazon-kinesis-client-python ↗

packagehttps://pypi.org/project/amazon-kclpy/ ↗

homepagehttps://aws.amazon.com/kinesis/ ↗