{"id":23243,"library":"amazon-kclpy","title":"Amazon Kinesis Client Library for Python","description":"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.","status":"active","version":"3.1.3","language":"python","source_language":"en","source_url":"https://github.com/awslabs/amazon-kinesis-client-python","tags":["kinesis","aws","stream-processing","kcl"],"install":[{"cmd":"pip install amazon-kclpy","lang":"bash","label":"Install from PyPI"}],"dependencies":[],"imports":[{"note":"Checkpointer is not directly exposed; use kcl.Checkpointer via the module.","wrong":"from amazon_kclpy.kcl import Checkpointer","symbol":"Checkpointer","correct":"from amazon_kclpy import kcl"},{"note":"KCLProcess is actually amazon_kclpy.kcl.KCLProcess; the top-level package does not export it.","wrong":"from amazon_kclpy import KCLProcess","symbol":"KCLProcess","correct":"from amazon_kclpy import kcl"}],"quickstart":{"code":"import os\nfrom amazon_kclpy import kcl\n\nclass SampleRecordProcessor(kcl.RecordProcessorBase):\n    def initialize(self, input_stream):\n        pass\n    def process_records(self, records, checkpointer):\n        for record in records:\n            print(record.data.decode('utf-8'))\n        checkpointer.checkpoint()\n    def shutdown(self, checkpointer, reason):\n        checkpointer.checkpoint()\n\nif __name__ == '__main__':\n    kcl.KCLProcess(SampleRecordProcessor()).run()","lang":"python","description":"Basic KCL record processor that prints records and checkpoints."},"warnings":[{"fix":"Remove any custom CheckpointManager implementations. If dual-stack endpoints are unavailable, stay on KCL v2.x.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Install JDK (8, 11, or 17) and ensure java is in PATH.\nOn Ubuntu: sudo apt install openjdk-11-jre\nOn macOS: brew install openjdk@11","message":"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'.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade to amazon-kclpy >=3.0.0 and update your record processor to match the v3 API (no custom checkpoint managers).","message":"KCL v2.x is in maintenance mode; no new features will be added. Users should migrate to v3.x.","severity":"deprecated","affected_versions":">=2.0.0, <3.0.0"},{"fix":"Ensure you install amazon-kclpy, not awskcl.\nCorrect: pip install amazon-kclpy\nWrong: pip install awskcl","message":"The pip package 'amazon-kclpy' is often confused with 'awskcl' (a community fork). The official AWS KCL Python package is 'amazon-kclpy'.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install JDK 17 or later, or ensure JAVA_HOME points to JDK >= 11.\nCheck: java -version\nInstall: sudo apt install openjdk-17-jre","cause":"Java version mismatch: KCL v3 requires JDK 11+ (class version 61 = Java 17), but older JDK (<= 55 = Java 11) is installed.","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"},{"fix":"Use the high-level KCLProcess API instead: from amazon_kclpy import kcl; kcl.KCLProcess(processor).run(). Do not import Checkpointer directly.","cause":"The internal API symbol 'Checkpointer' was removed in KCL v3; the class is no longer directly exposed.","error":"ImportError: cannot import name 'Checkpointer' from 'amazon_kclpy.kcl'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}