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
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}")
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.
fixInstall 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.
fixInstall 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.
fixInitialize `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.
fixEnsure 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.
fixInstantiate 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.