Turn any document into clean, LLM-ready Markdown.
PDF · DOCX · PPTX · XLSX · HWP/HWPX · ODF · RTF · EPUB · HTML · email · images — one function, no GPU, MIT licensed.
from opendockit import convert_file
result = convert_file("quarterly-report.hwp")
result.text # Markdown: headings, tables, lists, footnotes, LaTeX equations
result.sections # per page / slide / sheet — for chunking and citations ("page 3")
result.warnings # what was skipped or approximated, in plain sentencesMost converters handle the happy path. OpenDocKit is built for the files people actually upload.
- Structure, not just text. Merged table cells, multi-column PDFs, borderless tables, nested lists, footnotes, speaker notes, native charts as data tables, SmartArt as nested lists, Word / PowerPoint / Hancom equations as LaTeX, links and bold / italic as Markdown.
- First-class Korean documents. A from-scratch HWP 5.x parser, HWPX, CP949 detection, NFC normalization, and the form-heavy tables Korean offices produce. Most general-purpose converters cannot read these at all.
- Detects by content, not extension. An HTML table saved as
.xls, a CSV with a title block, an MHTML page named.doc— each is read as what it really is, and a warning tells you. - Safe on untrusted uploads. Zip bombs, runaway merged-cell counts, recursive PDF objects and multi-gigabyte images
are bounded.
IsolatedConverterruns every file in a disposable worker process with memory and time limits. - Images in place. Pictures, charts and scanned pages are extracted, filtered, and — if you plug in a vision model — described right where they appeared in the document.
- A hard character budget.
max_charsstops work instead of truncating afterwards, so a file that will be rejected anyway costs neither parsing time nor vision-model calls. - Permissive by default. MIT licensed; everything a plain
pip install opendockitbrings in is MIT / BSD / Apache-style (no PyMuPDF, no pyhwp), with no ML models and no GPU. The only copyleft code is behind the opt-inheicextra.
pip install opendockit # conversion only — never touches the network
pip install "opendockit[openai]" # + image description with a vision model
pip install "opendockit[heic]" # + HEIC/HEIF images (pulls in GPL/LGPL-licensed codec libraries)
pip install "opendockit[langchain]" # + LangChain loader
pip install "opendockit[llamaindex]" # + LlamaIndex reader
pip install "opendockit[mcp]" # + MCP server for agents
pip install "opendockit[open-webui]" # + document loader for Open WebUIRequires Python 3.12 or newer on Linux, macOS or Windows. On Windows a malformed HTML page or mail body over 256 K characters, or one nested very deeply, is read by an older parser and may lose content, with a warning (why).
Optional: install LibreOffice (brew install --cask libreoffice, apt install libreoffice)
to read legacy .doc and .ppt files. Every other format is read by OpenDocKit itself.
from opendockit import convert, convert_file
result = convert_file("report.pdf") # from a path
result = convert(data, "report.pdf") # from bytes (the filename is only a hint)
print(result.text)
print(result.char_count, result.exceeded) # size of the output, and whether the limit stopped itconvert is synchronous, offline and deterministic (the one exception: .doc and .ppt start a local LibreOffice
process). Pictures are collected in result.images and the text keeps an
[Image] placeholder where each one was.
from opendockit import OpenAIImageDescriber, aconvert
result = await aconvert(data, "report.pdf", describer=OpenAIImageDescriber()) # reads OPENAI_API_KEYCharts become data tables, diagrams become lists, scanned pages are transcribed, and decorative images are dropped.
OpenAIImageDescriber(model) accepts any LangChain chat model, and anything with an
async describe(image) -> str method works as a describer. See docs/images.md.
from opendockit import ConversionError, IsolatedConverter
async with IsolatedConverter(workers=2) as converter: # 2 GB and 2 minutes per file by default
try:
result = await converter.convert(data, filename)
except ConversionError as exc:
print(exc.code, exc) # stable code + a message safe to show usersOne bad file ends one worker; your server and the next upload carry on. In a script, run this under
if __name__ == "__main__": — the workers import the main module again. See docs/server.md.
opendockit report.pdf # Markdown on stdout, warnings on stderr
opendockit report.pdf --json # sections, metadata, warnings, images
opendockit report.pdf --count # just the character count
opendockit scan.pdf --describe # describe images with a vision model (uses OPENAI_API_KEY)from opendockit.integrations.langchain import OpenDocKitLoader
from opendockit.integrations.llama_index import OpenDocKitReader
docs = OpenDocKitLoader("report.pdf", mode="sections").load() # one Document per page / slide / sheet
docs = OpenDocKitReader(mode="sections").load_data("report.pdf")opendockit-mcp --root ~/Documents # MCP server: Claude, Cursor and other agents read your documents as MarkdownTo let the client start the server itself, with nothing installed beforehand, add it to the client's MCP settings:
{
"mcpServers": {
"opendockit": {
"command": "uvx",
"args": ["opendockit-mcp", "--root", "/path/to/documents"]
}
}
}With mode="sections" each page, slide or sheet is its own Document, with its number in the metadata for citations. See docs/integrations.md.
OpenDocKit is listed in the Hermes Agent plugin catalog, where every plugin is reviewed by the Hermes maintainers and pinned to one commit:
hermes plugins install opendockit
hermes plugins enable opendockitThen ask Hermes about a file on your machine in a new session. It reads a long document by page, slide or sheet, sends nothing anywhere and needs no API key. What the plugin runs, and how to limit the folders it may read: hermes-plugin/README.md.
Install the plugin from this repository, which is its marketplace:
/plugin install opendockit --marketplace hyeonsang010716/OpenDocKit
Then ask Claude about a document on your machine. It reads Word, PowerPoint, Excel and HWP/HWPX files, which its Read tool cannot open, and long PDFs by page. What the plugin runs, and how to limit the folders it may read: claude-plugin/README.md.
OpenDocKit is on the Dify Marketplace, reviewed by the Dify maintainers. In your Dify, open Plugins, find OpenDocKit in the Marketplace and install it. Then, in a Workflow or Chatflow:
- Add a File variable to the Start node. For HWP and HWPX, choose Other file types and add
.hwpand.hwpx. - Add the tool OpenDocKit → Convert to Markdown and pass it the file.
- Use its
textin an LLM node, ordocumentsfor one item per page, slide or sheet.
Dify reads no HWP or HWPX by itself. The file is converted inside your Dify, in a worker process with memory and time limits, with no API key and nothing sent anywhere else. Outputs and limits: dify-plugin/README.md.
opendockit-open-webui is a document loader for Open WebUI's External content extraction engine. Open WebUI sends
it every uploaded file and indexes one document per page, slide or sheet; a citation from a PDF names and opens the
right page. Open WebUI reads no HWP or HWPX by itself.
pip install "opendockit[open-webui]"
export OPENDOCKIT_OPEN_WEBUI_API_KEY=$(openssl rand -hex 32)
opendockit-open-webui --host 0.0.0.0 # then in Open WebUI: Documents → External, this URL and the same keyIn Admin Settings → Documents, set Content Extraction Engine to External, the loader's URL and the same API key. Each file is converted offline in a worker process with memory and time limits. Docker Compose, limits and errors: docs/integrations.md.
| Format | Sections | Highlights |
|---|---|---|
| page | reading order across columns, ruled and borderless tables, form field values, headings from font size, repeated header/footer removal, footnotes linked where the page proves them, scanned pages via vision model | |
| DOCX | document | heading styles, list numbering, merged cells, charts → tables, SmartArt, footnotes/endnotes, equations → LaTeX, comments |
| PPTX | slide | on-screen order, bullet levels, tables, charts → tables, SmartArt, equations, speaker notes |
| XLSX · XLS · Excel 2003 XML · CSV | sheet | several tables per sheet, merged cells, number and date formats, charts, cell comments |
| HWP · HWPX | document | outline headings, numbering, merged cells, captions, footnotes, equations → LaTeX |
| ODT · ODS · ODP | document / sheet / slide | read directly from the package: headings, lists, merged cells, charts, formulas → LaTeX, speaker notes |
| RTF | document | built-in parser: legacy code pages (CP949), tables with merged cells, lists, footnotes, pictures |
| EPUB | document | chapters in reading order, pictures stored in the book, metadata |
| DOC · PPT | document / slide | converted through LibreOffice when it is installed, then read like DOCX / PPTX |
| HTML · MHTML | document | tables with rowspan/colspan, layout tables unwrapped, MathML → LaTeX, hidden elements removed |
Email (.eml, mbox) |
document | headers, HTML or plain body, forwarded messages, calendar invites |
| TXT · Markdown | document | encoding detection (UTF-8, CP949, UTF-16, Windows-1252) |
| Images | document / page | JPEG, PNG, WebP, GIF, BMP, TIFF, AVIF, and HEIC with the heic extra — described by a vision model |
Legacy .doc and .ppt need LibreOffice installed; everything else is read by OpenDocKit itself. The full list of
what each format restores is in docs/formats.md; the honest list of what it cannot do is in
docs/limitations.md.
We ran OpenDocKit, MarkItDown, Kreuzberg, Unstructured and Docling on the same files on a standard GitHub runner (method, raw results and how to rerun it):
- Structure — OpenDocKit keeps the most: 49 of 49 checks such as "is the merged cell still attached to its row", against 36 for the next tool. The checks are ours, and 0.2.0 was written with them known; the report says what that means.
- Formats — it reads 26 of the 31 formats tested without any model or service, the most of the five, and is the only one that reads HWP and HWPX.
- Not the fastest, and no OCR — scans and images are read only through a vision model, where Docling and
Unstructured read them offline. Kreuzberg is about thirty times faster, and legacy
.doc/.pptcost about a second each because they go through LibreOffice.
examples/ has one sample document per format and the Markdown OpenDocKit produces from each — with and
without a vision model — so you can judge the output before installing anything.
| Formats | What is extracted from each format and how it is rendered |
| Options | ConvertOptions, exceptions and error codes |
| Images | Extraction, filtering, vision models, custom describers |
| Running on a server | IsolatedConverter, resource limits, the character budget |
| Integrations | LangChain, LlamaIndex, the MCP server, Hermes Agent, Claude Code, Dify and Open WebUI |
| Integration guide | What an upload UI should tell its users |
| Design | Why it is built this way, and how it was verified |
| Limitations | Known gaps, stated plainly |
| Decision records | Every deliberate trade-off, with the test that pins it |
Contributions are welcome — bug reports with a minimal reproducing document are especially valuable. Start with CONTRIBUTING.md.
git clone https://github.com/hyeonsang010716/OpenDocKit.git && cd OpenDocKit
uv sync
uv run pytest -n auto -m "not timing" # the bulk of the suite, in parallel
uv run pytest -m timing # tests that measure time, one at a time
uv run ruff check