Chonkie: a chunking library for RAG pipelines, and what its install layout costs you
🦛 CHONK docs with Chonkie ✨ — The lightweight ingestion library for fast, efficient and robust RAG pipelines
At a glance
- What is it?
- Chonkie packages seven chunker strategies, a refinery step, a Pipeline object and a self-hosted FastAPI server under an MIT licence. The interesting part is not the chunkers. It is the minimum-install rule, which pushes dependency decisions onto you.
- Who is it for?
- Adopt Chonkie if you are building a retrieval pipeline in Python and want the chunking and refinement steps expressed as composable objects rather than a script you keep rewriting. Do not adopt it if you want a single dependency that does everything at a predictable install size, or if your chunking logic is already stable and tested.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Chonkie targets: chunking code that gets rewritten for every project
Chunking is the step in a RAG pipeline that everyone writes themselves and nobody maintains. The README opens by naming exactly this: people tired of making their gazillionth chunker and tired of the overhead of large libraries. Chonkie is the maintainers' answer to both complaints at once, which is a harder position than it sounds, because the two complaints pull in opposite directions. A library that covers every chunking strategy is large by definition. A library that stays small cannot cover every strategy.
The audience is Python developers building retrieval systems who have already decided they need control over how documents are split. If you are using a hosted ingestion service and never look at chunk boundaries, Chonkie is not aimed at you. If you have ever tuned a chunk size, added an overlap, or debugged why a retrieved passage started mid-sentence, you are the intended user. The repository topics confirm the scope: chunking-algorithm, text-splitter, semantic-chunker, retrieval-systems.
Seven chunkers, and where the real design decision sits
The README lists the chunkers in a table with names and aliases. TokenChunker splits into fixed-size token chunks. SentenceChunker splits on sentences. RecursiveChunker splits hierarchically using customizable rules. SemanticChunker splits on semantic similarity and credits Greg Kamradt's work as the inspiration. LateChunker embeds text first and then splits it, so the resulting chunk embeddings are better aligned with the boundaries. CodeChunker handles source code. FastChunker is described as SIMD-accelerated byte-based chunking, included in the default install.
That last detail is the one worth pausing on. FastChunker is the only chunker the README explicitly says ships in the default install. Everything else is subject to the minimum-install rule, which the README states directly: install only what you need, and if you do not want to think about it, install chonkie[all], which it marks as not recommended for production environments. So the default pip install chonkie gets you a working library with a byte-level chunker, and the moment you want semantic splitting you are choosing an extra. The README does not enumerate which extra maps to which chunker in the section provided. That mapping lives in the docs, and it is the first thing to check before you plan a deployment.
The Pipeline object and how data flows through it
The basic usage example is three lines: import RecursiveChunker, instantiate it, call it on a string. The return value is iterable, and each chunk exposes at least chunk.text and chunk.token_count. That is the whole surface for the simple case, and it is a good surface.
The Pipeline example shows the more interesting mechanism. You build a chain by calling methods that each return the pipeline, so the calls stack. The README's example chains chunk_with("recursive", tokenizer="gpt2", chunk_size=2048, recipe="markdown"), then chunk_with("semantic", chunk_size=512), then refine_with("overlap", context_size=128), then refine_with("embeddings", embedding_model="sentence-transformers/all-MiniLM-L6-v2"). Two chunking passes in sequence, then two refinement passes. The chunk_with calls take the chunker alias from the table plus keyword config, and refine_with takes a refinery alias plus its own config.
The data flow is: pipe.run(texts=...) returns a doc object, and doc.chunks holds the result. There is also an async path, pipe.arun(texts=...), which the README frames as being for high-throughput applications. The presence of both run and arun on the same object matters more than it looks. It means the pipeline is not a thin wrapper over a synchronous function; the async path is a first-class entry point, and a pipeline built once can be driven either way.
Running it: install, chunk, serve
The install commands are pip install chonkie or uv pip install chonkie, with uv presented as the faster option. The full install is pip install "chonkie[all]", and the README repeats its warning that this is not recommended for production. The package size badge in the README reads 505KB, which is the headline claim behind the lightweight positioning, though the badge measures the package, not the dependency tree you end up with after adding extras.
The API server is a separate path. The README gives pip install "chonkie[api,semantic,code,catsu]" as the install for it, noting that this includes catsu for multi-provider embeddings. Then chonkie serve starts it, with flags documented as --port, --reload and --log-level, for example chonkie serve --port 3000 --reload --log-level debug. If you would rather not use the CLI, the README shows uvicorn chonkie.api.main:app --host 0.0.0.0 --port 8000, and docker compose up as a third route.
The server exposes endpoints for chunkers, refineries and pipelines. Pipelines on the server are described as reusable workflow configurations stored in a local SQLite database, which is a meaningfully different thing from the in-process Pipeline object. You create one with a POST to /v1/pipelines carrying a JSON body with a name and a steps array, where each step has a type, a chunker or refinery name, and a config object. You list them with a GET to /v1/pipelines. Interactive documentation is served at /docs. Note the ports in the README's own examples disagree: chonkie serve defaults are not stated, the CLI example uses 3000, and the uvicorn example uses 8000. Check which one your setup actually binds.
The minimum-install rule is a cost you pay later
The README sells the install layout as a feature and calls it the rule of minimum installs. It is a real trade-off and it deserves to be stated as one.
On the benefit side, a service that only needs RecursiveChunker does not pull in embedding model dependencies. That is a genuine win for container image size and cold-start time, and it is the reason the 505KB figure is plausible for the base package.
On the cost side, the dependency surface of your application is now determined by which chunkers you happen to use, and that can change. A team that starts with RecursiveChunker and later adds a semantic pass has changed its install line, its lockfile and its image, and possibly its deployment pipeline. The chonkie[all] escape hatch exists precisely because this is annoying, and the README's own advice against using it in production means the escape hatch is not a real answer for production systems. You are expected to curate. That is defensible engineering, but it is work, and it is work that recurs every time the chunking strategy changes.
A second limitation is visible in the README's own framing. The library is described as chunking that just works, but the Pipeline example requires you to name a tokenizer (gpt2), a chunk size, a recipe (markdown), an embedding model, and an overlap context size before you get anything useful. That is not a complaint about the API. It is a note that the defaults carry less of the weight than the tagline suggests, and that the quality of your retrieval output still depends on the values you pick.
Where Chonkie sits against LangChain's text splitters
The obvious comparison is LangChain's text splitter modules, which most Python RAG projects already have in their dependency tree. The difference in approach is architectural, not feature-by-feature.
LangChain's splitters are components inside a larger framework. You get them along with chains, agents, memory abstractions and a large dependency graph, and you configure them through the same conventions as everything else in that framework. Chonkie inverts this. It is a chunking library with a pipeline object attached, and the pipeline exists to sequence chunkers and refineries, not to orchestrate a whole application. If you already use LangChain for retrieval, adding Chonkie means adding a second dependency for one stage of the pipeline. That may be worth it if you want the SemanticChunker or LateChunker behaviour and do not want to write it, and it may not be worth it if RecursiveCharacterTextSplitter already does what you need.
The other difference is the server. LangChain does not ship a REST API for text splitting. Chonkie does, with pipelines persisted in SQLite. That makes Chonkie viable as a standalone ingestion service that a non-Python client can call, which is a use case LangChain's splitters do not address at all. Whether you want a separate ingestion service is a separate question, but the option is there and it is not an afterthought in the README.
Maintenance, versioning and the MIT licence
The release history in the material shows v1.6.8-alpha.1, then v1.6.8, then v1.7.0, with roughly a month between the last two. That is an active release cadence on a project that is not archived and was pushed to recently. Active cadence cuts both ways for an ingestion dependency. You get fixes, and you also get churn in the API surface you depend on.
There is a specific signal worth reading carefully: the presence of an alpha tag in the release list. If the project publishes pre-releases alongside stable ones, and your install line is unpinned, you can resolve to a pre-release. Pin your Chonkie version in your lockfile and upgrade deliberately, especially if you are relying on Pipeline or refinery behaviour, which is where the chaining logic lives and where a change would ripple through your ingestion code.
The licence is MIT, and the README carries the standard MIT badge linking to the LICENSE file. MIT is permissive: it allows commercial use, modification and redistribution with the licence notice preserved. It does not grant patent rights explicitly, and it does not require the maintainers to keep publishing. That is normal for this class of library and it is the reason a fork is a viable fallback if the project's direction stops matching yours. This is a description of the licence, not legal advice; if your organisation has specific requirements around dependency licensing, route it through whoever handles that.
The maintenance cost you should budget for is not the library itself. It is the extras. Every chunker you adopt is a dependency decision, and every dependency decision is something you re-evaluate when you upgrade. The README's own recommendation against chonkie[all] in production tells you the maintainers expect you to do that work.
Editorial conclusion
Adopt Chonkie if you are building a retrieval pipeline in Python and want the chunking and refinement steps expressed as composable objects rather than a script you keep rewriting. Do not adopt it if you want a single dependency that does everything at a predictable install size, or if your chunking logic is already stable and tested. Before committing, verify two things in your own environment: which extras your chosen chunker actually requires, since the default install does not cover all of them, and whether the Pipeline and refinery APIs you plan to chain have stayed stable across the v1.6 to v1.7 releases. The MIT licence gives you the freedom to fork if they have not.
Community notes