Registry / ai-ml / chonkie

chonkie

JSON →
library1.6.8pypypi✓ verified 86d ago

Chonkie is a no-nonsense Python library for text chunking, offering various strategies including recursive, semantic, and AI-powered chunkers. It also supports advanced features like HTML table processing and visualization. Chonkie is actively maintained with frequent minor releases and bug fixes, with the current version being 1.6.2.

pip install chonkie
INSTALL
IMPORT
SIG · CHONKIE
C
chonkie
ai-mlpythonv1.6.8
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.6.8 · 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
✕ build_error
8/12 runs
py 3.11
✕ build_error
8/12 runs
py 3.12
✕ build_error
8/12 runs
py 3.13
✕ build_error
8/12 runs
py 3.9
✕ build_error
8/12 runs
Code
Verified usage

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

RecursiveChunker
from chonkie import RecursiveChunker
TeraflopAIChunker
from chonkie import TeraflopAIChunker
New in v1.6.2, requires `teraflopai` dependency (part of `[llm]` or `[all]` extras) and an API key.
Visualizer
from chonkie import Visualizer
Allows visualizing chunking results.
FastChunker
from chonkie import FastChunker
LateChunker
from chonkie import LateChunker

This quickstart demonstrates how to use the `RecursiveChunker` to break down a sample text into smaller pieces. It's a common and flexible chunking strategy. An commented-out example for `TeraflopAIChunker` is also included, highlighting the need for an API key and optional dependencies.

import os from chonkie import RecursiveChunker # Instantiate a chunker. RecursiveChunker is a common choice. chunker = RecursiveChunker(chunk_size=500, chunk_overlap=50) text = ( "Chonkie is a highly efficient and flexible text chunking library in Python. " "It provides various strategies for breaking down long documents into smaller, " "manageable chunks, which is crucial for many NLP applications like RAG. " "The library supports different chunking methods, including recursive, semantic, " "and AI-driven approaches, and can handle various input formats like raw text and HTML. " "Recent versions have introduced features like HTML table support and CLI tools." ) # Chunk the text chunks = chunker.chunk(text) print(f"Original text length: {len(text)} characters") print(f"Number of chunks: {len(chunks)}") for i, chunk in enumerate(chunks): print(f"Chunk {i+1} (length {len(chunk)}): {chunk[:100]}...") # Example with TeraflopAIChunker (requires API key and 'llm' extra) # from chonkie import TeraflopAIChunker # teraflop_api_key = os.environ.get('TERAFLOPAI_API_KEY', 'YOUR_TERAFLOPAI_API_KEY') # if teraflop_api_key != 'YOUR_TERAFLOPAI_API_KEY': # try: # ai_chunker = TeraflopAIChunker(api_key=teraflop_api_key) # ai_chunks = ai_chunker.chunk(text) # print(f"\nAI Chunker chunks: {len(ai_chunks)}") # except Exception as e: # print(f"Could not use TeraflopAIChunker: {e}")
Debug
Known issues
breakingChonkie v1.5.0 dropped support for Python 3.9. Users on Python 3.9 must upgrade their Python version to 3.10 or newer to use Chonkie v1.5.0 or later.
fix
Upgrade your Python environment to 3.10 or higher (e.g., `python -m pip install --upgrade python` or use a new virtual environment).
affects: >=1.5.0
gotchaMany advanced chunkers (e.g., OpenAI, TeraflopAI, LangChain-based) and visualization tools have optional dependencies that are not installed with `pip install chonkie`. Attempting to use these features without the correct dependencies will result in `ModuleNotFoundError`.
fix
Install Chonkie with the relevant extras, for example `pip install 'chonkie[llm]'` for LLM-related features, or `pip install 'chonkie[all]'` for all extras.
affects: All versions
gotchaBefore v1.5.5, importing the `chonkie` library could fail with a `ModuleNotFoundError` if `openai` was not installed, even if you did not intend to use OpenAI-specific features. This was due to non-lazy imports.
fix
Upgrade to Chonkie v1.5.5 or newer, which includes a fix for lazy imports, or ensure `openai` is installed if using older versions.
affects: <1.5.5
gotchaThe `TeraflopAIChunker` (introduced in v1.6.2) requires an API key for its service. Without a valid API key, initialization or chunking attempts will fail.
fix
Obtain an API key from TeraflopAI and provide it during chunker initialization (e.g., `TeraflopAIChunker(api_key="your_key")`).
affects: >=1.6.2
gotchaChonkie migrated its performance-critical components from Cython to Rust in v1.5.4. While this is largely an internal change, it might affect build environments or specific performance characteristics for advanced users compiling from source.
fix
Ensure your environment has Rust toolchain if building from source. For most users installing via `pip`, pre-built wheels should handle this transparently.
affects: >=1.5.4
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'openai'
This error occurs when attempting to use features of Chonkie that rely on the OpenAI library without 'openai' being installed, or when Chonkie's internal lazy import fails due to an older version or specific environment configurations.
fix
Install the OpenAI dependency using pip: `pip install "chonkie[openai]"` or `pip install openai`.
ImportError: ('text-embedding-3-small is not a valid embedding model', 'Please install the `semantic` extra to use this feature')
This error arises when using semantic chunking features, such as `SemanticChunking`, without the necessary 'semantic' extra dependencies installed, which include libraries like `sentence-transformers` for embedding models.
fix
Install the required 'semantic' extra: `pip install "chonkie[semantic]"`.
AttributeError: type object 'RecursiveChunker' has no attribute 'from_recipe'
The `from_recipe` class method for `RecursiveChunker` was deprecated or removed, and the chunker now expects direct initialization with parameters or specific recipe loading mechanisms.
fix
Initialize `RecursiveChunker` directly with its parameters. If you intended to use a recipe, consult the latest Chonkie documentation for the updated way to apply pre-defined chunking rules, which might involve passing a `rules` object.
ValueError: Mismatched number of chunks and embeddings.
This error typically occurs during the ingestion process into a vector store when the number of generated text chunks does not match the number of corresponding embedding vectors.
fix
Ensure that the chunking and embedding steps are properly synchronized, and that an embedding is generated for every chunk. Debug the chunking and embedding pipelines to identify where the mismatch is occurring (e.g., failed embedding calls for certain chunks).
TypeError: SemanticChunker initialization fails when embedding_model parameter is not provided or is explicitly set to None.
The `SemanticChunker` class requires an `embedding_model` to be explicitly provided or configured, and does not automatically fall back to a default if `None` is passed.
fix
Instantiate the `SemanticChunker` with a valid embedding model, for example: `from chonkie.chunker import SemanticChunker; from chonkie.embedding import OpenAIEmbedder; chunker = SemanticChunker(embedder=OpenAIEmbedder())` or specify a model string directly if supported.
Upgrade
Version history
1.6.8latest on PyPI · released Jun 1, 2026
Audit
Dependencies
httpxoptionalUsed for HTTP requests, especially by some AI-powered chunkers.
orjsonoptionalUsed for faster JSON processing.
openaioptionalRequired for OpenAI-based chunkers.
langchainoptionalRequired for LangChain-based chunkers.
Agent activity
21 hits · last 30 days
node
16
Amazon
1
OpenAI (training)
1
Resources
chonkie — pip install chonkie · libregistry