Install chunk-engine for Python (pip), JavaScript (npm), or Rust (cargo) — requirements, wheels, pinning, and the failure modes worth knowing.

One engine, three packages. Pick your language and the rest of this page follows it.

Showing examples for Python

— your choice follows you across the docs.

$pip install py-chunks

Requirements

	Python	JavaScript	Rust
Package	`py-chunks` (PyPI)	`js-chunks` (npm)	`rs-chunks` (crates.io)
Import name	`py_chunks`	`js-chunks`	`chunks_rs`
Minimum runtime	CPython 3.9	Node 18 (`engines`)	Rust 2021 edition
Delivery	prebuilt `cp39-abi3` wheel	WASM, loaded on first call	source crate
Runtime dependencies	none	none	see `Cargo.toml`
Toolchain needed	none on a wheel platform	none	cargo
Types	`py.typed` + stubs	TypeScript declarations	native

Wheel platforms. The Rust engine is compiled into the wheel against CPython's stable ABI (abi3-py39), so one wheel per platform covers CPython 3.9 through 3.13+ — there is no per-version wheel matrix and no source build.

Platform	Wheel tag	Built
Linux x86_64 (glibc ≥ 2.28)	`manylinux_2_28_x86_64`	yes
Linux aarch64 (glibc ≥ 2.28)	`manylinux_2_28_aarch64`	yes
macOS Apple Silicon	`macosx_*_arm64`	yes
macOS Intel	`macosx_*_x86_64`	yes
Windows x86_64	`win_amd64`	yes
Anything else (musl/Alpine, Windows ARM64, BSD)	—	source build from the sdist

An sdist is published too, so unlisted platforms still install — they just compile the Rust engine, which needs a Rust toolchain. pip must be new enough to understand PEP 600 tags (pip 20.3+) or it will ignore the manylinux wheels and reach for the sdist unnecessarily.

No runtime dependencies. PDF parsing is pure Rust inside the wheel, and PDFium — needed only to rasterise a scanned PDF's pages when it carries no embedded page image of its own — is vendored into the same wheel. pip install py-chunks pulls nothing else.
Typed. The package ships a py.typed marker and stubs for the compiled module, so mypy and pyright see full annotations.

Bundlers (vite/webpack)

Bundling concerns js-chunks only. Switch the language selector above to JavaScript to read this section.

Verify

A post-install smoke test: the import resolves, the engine loads, chunks come back. Point it at any Markdown file — the counts in the comments are for the small notes.md used throughout these docs, so yours will differ; what matters is that a number and a content_type come back at all.

verify.py

import py_chunks
from py_chunks import get_chunks

print(py_chunks.__version__)                 # 0.6.4
print(len(get_chunks("notes.md")))           # 7
print(get_chunks("notes.md")[0]["content_type"])   # heading

py_chunks.__version__ is read from the installed distribution's metadata, so it reports 0.0.0+unknown if you are running from a source tree that was never installed. That is the fastest way to spot a stale pip install -e ..

Troubleshooting

Symptom	Cause	Fix
Install starts compiling Rust	No wheel for your platform (musl/Alpine, Windows ARM64, BSD), or `pip` too old to read PEP 600 tags	`pip install -U pip`, or install a Rust toolchain and let the sdist build
`ERROR: … requires a different Python`	You are on 3.8 or older	`requires-python` is `>=3.9`; upgrade Python
`ImportError: … _rust …` after an editable install	The compiled module was not rebuilt	`maturin develop` / reinstall; a stale `.so` outlives the Python change
`py_chunks.__version__` reads `0.0.0+unknown`	Running from a source tree with no installed distribution metadata	Install the package rather than adding the directory to `sys.path`
`ValueError: Unsupported file type '.xyz'`	Dispatch is by extension	Pass the real extension — with bytes, that means the `filename` argument
mypy/pyright see `Any`	Stubs not picked up	Confirm `py.typed` is in the installed package; do not shadow it with a local `py_chunks/` directory

Pinning and upgrading

The three packages share one version number and are released together — from 0.6.0 onward, py-chunks, js-chunks and rs-chunks always move in lockstep. If you use more than one SDK against the same index, pin them to the same version.

pip install "py-chunks==0.6.4"        # exact
pip install "py-chunks~=0.6"          # 0.6.x only
pip install -U py-chunks              # upgrade

Re-index after a chunking upgrade

Chunk text and boundaries changed in 0.6.0 across PDF, .doc, .txt, .md, email and OpenDocument — almost always because more text is extracted or laid out correctly. Embeddings generated with 0.5.x will not match text produced by 0.6.x, so an index built before the upgrade must be rebuilt. See the 0.6.0 release notes.

0.6.1 and 0.6.2 are packaging, typing, argument validation and error ergonomics only — no chunk output changed, so upgrading anywhere within 0.6.x needs no re-index. See 0.6.1 and 0.6.2.

Next steps

Quick Start — your first chunks, and how to pick a mode
Input Sources — paths, bytes, uploads, URLs, Blobs
Languages & parity — choosing an SDK, and how they stay identical
API Reference — every signature, per language

Installation