Install & Compatibility
Where this runs
tested against v0.3.7 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.115s · 48.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.5s · import 0.101s · 48MB
47MB installed
● package 47MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Chunkr
✓ from chunkr_ai import Chunkr
ChunkProcessing
✓ from chunkr_ai.models import ChunkProcessing
Configuration
✓ from chunkr_ai.models import Configuration
Tokenizer
✓ from chunkr_ai.models import Tokenizer
This quickstart demonstrates how to initialize the Chunkr client and submit a document for processing. It assumes you have an API key set as an environment variable. After submission, you can monitor the task status or retrieve the output through the Chunkr AI dashboard or further API calls.
import os
from chunkr_ai import Chunkr
from chunkr_ai.models import ChunkProcessing, Configuration, Tokenizer
# Ensure your Chunkr API key is set as an environment variable CHUNKR_API_KEY
api_key = os.environ.get('CHUNKR_API_KEY', '')
if not api_key:
print("Warning: CHUNKR_API_KEY environment variable not set. The API call will likely fail.")
chunkr = Chunkr(api_key=api_key)
# Example of processing a document (replace with your document URL or file path)
# This example uses default chunking strategies.
try:
task = chunkr.parse_document(file_url="https://example.com/document.pdf")
print(f"Document processing task submitted with ID: {task.task_id}")
# You can poll for the task status or set up webhooks
# For a simple quickstart, we'll just acknowledge submission.
print("Check Chunkr AI dashboard or use get_task_output for results.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
gotchaThe Python SDK is currently in alpha and requires the `--pre` flag for installation. This indicates that the API might be subject to changes before a stable release.fixAlways install with `pip install chunkr-ai --pre`. Consult the official documentation for the latest installation instructions and API stability updates.
affects: 0.3.7 and earlier pre-release versions
breakingThere are two distinct versions: an open-source AGPL self-hosted version and a fully managed Cloud API. They use different underlying models (community/open-source vs. proprietary in-house), leading to differences in accuracy, speed, and available features (e.g., Excel support is Cloud API exclusive).fixCarefully consider your use case. For production workloads and higher performance, the Cloud API is recommended. Ensure you are using the correct client and configuration for the chosen platform. If self-hosting, be aware of the capabilities and limitations of the open-source models.
affects: All versions
gotchaAPI key is required for authentication with the Chunkr AI Cloud API. Failing to provide a valid key will result in authentication errors.fixObtain an API key from your Chunkr AI dashboard after creating an account. Set it as an environment variable (e.g., `CHUNKR_API_KEY`) and pass it to the `Chunkr` client upon initialization.
affects: All versions
gotchaSuboptimal chunking strategies can lead to increased AI costs, reduced retrieval accuracy, and inconsistent LLM responses. While Chunkr aims for intelligent chunking, users should be aware of how different strategies impact their RAG systems.fixReview Chunkr's documentation on custom chunking strategies, VLM processing, and configuration options. Experiment with `ChunkProcessing`, `Configuration`, and `Tokenizer` parameters to optimize chunk size and content for your specific use case and LLM.
affects: All versions
Upgrade
Version history
0.3.7latest on PyPI · released Aug 6, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.