Turn any document into clean, AI-ready Markdown. Local-first · reads scanned PDFs · up to 6× fewer tokens than vision models
Works with PDF · DOCX · PPTX · XLSX · EPUB · HTML · CSV · JSON · XML · TXT · MD · images · audio
-3b82f6.svg){kind=icon}
Full / offline-ready downloads · Cross-platform docs · Website · The proof · How it compares · Report a bug · ❤️ Sponsor
For the easiest setup, download Full. Everything needed for document conversion and OCR is included in one download.
Not sure which edition to choose? Download Full.
Everything is packaged together, so there are no additional MDFlux setup downloads when you open it.
Prefer a smaller first download? Windows Lite (4.9 MB) · Linux Lite (5.8 MB)
Lite downloads and installs the required components when you first open it.
Getting a document into a shape an LLM can use is more annoying than it should be. You either dump the raw text and lose every heading, table, and list, or you ship your pages to a cloud vision model as images, which means your documents leave your machine and you pay by the page to read your own files. And scanned PDFs? Plain text extractors just hand you back nothing. The text is right there, and the tool acts like the page is blank.
MDFlux is what I wanted instead. Drop in a file or a folder and get back clean, structured Markdown, with OCR for those "blank" scanned pages, batch processing for a whole directory, and an optional cleanup pass to tidy up messy extraction. It runs entirely on your machine. It's built on Microsoft's MarkItDown, with everything around it that makes the engine actually usable day to day.
Every time a document gets read by an LLM, you pay for it in tokens. The common way to feed a document to a model is to send its pages as images to a vision model, and images are an expensive way to spend tokens. MDFlux hands the model clean Markdown instead, which is far cheaper to read and reuse.
Why clean Markdown costs fewer tokens than feeding documents to AI:
- You pay for pixels, not words. A page sent to a vision model as an image costs a fixed chunk of tokens (often well over a thousand) no matter how little text is on it. The same page as Markdown is usually a few hundred.
- Plain text tokenizes efficiently. Markdown is just text, with no image data, no markup bloat, no base64 blobs.
- Clean beats raw. MDFlux strips the broken layout, repeated whitespace, and junk characters that pad out messy extractions, so you don't spend tokens on noise.
- Structure stays compact. Headings, tables, and lists carry the document's meaning in very few tokens, so the model understands more for less.
- It compounds. The saving lands on every single call that reads the document, so it multiplies across a pipeline or a batch instead of happening once.
About 2 to 6 times fewer tokens than vision. For ordinary documents, MDFlux Markdown runs around 4 times lighter than sending the pages as images, and up to 5.7 times lighter on scanned pages. That saving lands on every single call that reads the document, so it compounds quickly across a pipeline or a large batch.
And it reads what other tools return empty. Point a plain extractor at a scanned, image-only PDF and you get zero usable text. MDFlux's OCR recovers it, and even then it stays lighter than the vision route:
| Scanned, image-only PDF | Usable tokens of text |
|---|---|
| Plain text extractor | 0 |
| Vision model (page as an image) | 10,731 |
| MDFlux (OCR to Markdown) | 1,893 |
That's the full text recovered in about 5.7 times fewer tokens than the vision model, which still has to OCR the image on its end anyway.
Full / offline-ready downloads · Editions & platforms · Free & MIT-licensed · No account, no cloud
| 💸 Fewer tokens, lower cost | Clean Markdown costs about 2 to 6 times fewer tokens than sending pages to a vision model, so every LLM call that reads the document is cheaper. |
| 🔒 Local and private | Your documents never leave your machine. No cloud, no API key, no account. |
| 🔍 Reads scanned PDFs | Built-in OCR recovers text from scans that other tools treat as blank. |
| 🧱 Real structure | Proper Markdown with headings, tables, and lists intact. Readable, greppable, diff-able. |
| 🖥️ No terminal needed | Portable app. Unzip, run, click through a one-time setup. Done. |
| 📦 Many formats | PDF, DOCX, PPTX, XLSX, EPUB, HTML, CSV, JSON, XML, TXT, Markdown, images, and audio. |
| 🔁 Batch a whole folder | Convert everything at once, with progress, cancellation, and per-file diagnostics. |
| 🧹 Optional cleanup | Off, rule-based, or an AI pass (local or API). The Changes tab shows what cleanup added or removed. |
- Cross-platform release matrix: Windows and Linux x64 (glibc) Lite and Full archives.
- Lite and Full editions: Lite provisions dependencies transactionally on first launch; Full bundles an immutable runtime and never installs packages at runtime.
- Runtime reliability: recoverable provisioning, offline-ready Full operation, and clearer runtime health and repair diagnostics.
- AI cleanup: more predictable cleanup behavior and clearer provider/runtime diagnostics.
- Issue fixes: AI cleanup timeout resilience (#25), Linux support (#28), and OCR dependency/provisioning reliability through Lite recovery and the bundled Full runtime (#30).
- Changes tab: added and removed lines after cleanup.
- OCR: newer on-device engine for scans.
- AI cleanup: pick DeepSeek, OpenAI, Groq, or another provider in Diagnostics, then Test the key.
- Drop
.txtand.mdlike any other file.
If you already had OCR from 0.1.0, reinstall it from Diagnostics.
🤖 AI and RAG builders: feed clean, structured source documents to any model instead of raw text or pricey vision tokens
🔬 Researchers: batch-convert papers, reports, and scanned archives into searchable Markdown
🧑💻 Developers: get diff-able, version-controllable text out of binary document formats
📝 Writers and analysts: pull clean copy out of PDFs and Office files without the formatting mess
🔒 Privacy-conscious users: convert sensitive contracts, records, and decks with nothing ever uploaded
1. Drop a file or folder → PDF, Office, EPUB, scans, audio, and more
2. Pick a cleanup mode → Off, rule-based, or AI (local or API)
3. Get clean Markdown → Preview, Source, Split, or Changes. Copy or save as .md.
The first launch sets up a private, self-contained Python environment (one time, needs internet). Every conversion after that runs fully offline.
Cleanup modes: Off, rule-based, or an AI pass, chosen per run.
The Changes tab after cleanup: what was added or removed, line by line.
01 · Select. Grab a folder of mixed files: Word, PowerPoint, Excel, PDFs, scans, web pages, anything. No conversion settings to pick.
02 · Convert. One drop turns the whole batch into AI-ready Markdown, locally. OCR recovers text from scans that other tools read as empty.
03 · Stays healthy. Dependency health and diagnostics run on-device, so you can see exactly what's installed and working.
MDFlux is built on Microsoft's MarkItDown, which is a genuinely great conversion library. What MDFlux adds is everything around it: the OCR for scans, the desktop app, the batching, the reliability, and the privacy-by-default packaging that lets anyone run it against a folder of files without touching a command line.
| Microsoft MarkItDown | MDFlux | |
|---|---|---|
| Core conversion engine | yes | yes (uses MarkItDown) |
| Scanned / image-only PDFs | returns roughly 0 characters | built-in OCR recovers the text |
| Install and run | pip install plus a terminal |
portable app, no terminal |
| Dependency setup | manual (pip, ffmpeg, OCR extras) | sets itself up on first launch |
| Batch a whole folder | write your own script | built in, runs concurrently with progress |
| Timeouts and cancel | can hang with no feedback | every job streams progress and can be cancelled |
| Cleanup modes | raw output | Off, rule-based, or AI cleanup (local or API) |
| Preview and diagnostics | none | rendered preview plus a health panel |
| Audio transcription | plugin or Azure | local, built in |
| Privacy | local if you wire it up | local by default |
On already-clean files the output is close to identical, because under the hood it is MarkItDown. The point isn't to beat the engine. It's to make that engine genuinely usable.
MDFlux is one cross-platform product with two editions on each supported platform:
| Edition | Download size | Python setup | Best for |
|---|---|---|---|
| Lite | Smaller archive | One-time transactional provisioning (internet on first launch) | Most users; smaller download |
| Full | Larger archive | Immutable bundled runtime — no package installs at runtime | Offline / air-gapped use |
Supported platform identifiers: windows-x64 and linux-x64-glibc (x64 only). Speech model
weights are on demand in both editions.
Release status: v0.3.0 introduces verified Windows and Linux x64 Lite and Full archives. Windows v0.2.0 remains available under the legacy Lite-style name
MDFlux_<version>_portable.zip. Each v0.3.0 archive is verified before the release is published; see docs/cross-platform/README.md.
Full details: editions · platforms & support · releases & verification
Requirements: Windows 10 or 11 (x64) with WebView2 (ships with current Windows). Linux x64
(glibc, Ubuntu 22.04+) needs WebKitGTK 4.1 (libwebkit2gtk-4.1-0) — including Full edition
builds. macOS is on the roadmap.
1. Download and run. Get the portable archive from Releases. On Windows, extract the zip and double-click MDFlux.exe. No installer, no admin rights. Linux Lite/Full tarballs with frozen names are pending the cross-platform release — see setup guide for contributor builds.
SmartScreen warning? The build is open source and unsigned. Click "More info" then "Run anyway". You'll need the WebView2 runtime, already on current Windows 10/11.
2. First launch (one-time, internet required). MDFlux sets up a private, self-contained Python environment. This happens once. After that, it runs fully offline.
3. Convert. Drop a document onto the window, pick a cleanup mode, and click "Convert to AI-Ready Markdown". Preview it, then copy straight from the preview or save as .md. For a whole folder, you pick an output folder up front and every converted file lands there.
To verify your download, check the SHA-256 posted on the release page. After cross-platform integration, use the artifact verifier for Lite and Full archives.
| Documents | Office | Web and data | Other |
|---|---|---|---|
| PDF (including scanned, via OCR) | DOCX | HTML | Audio to transcript (MP3, WAV, M4A, OGG, FLAC, AAC) |
| EPUB | PPTX | CSV, JSON, XML | Images via OCR (PNG, JPG, GIF, WEBP, TIFF, BMP) |
| TXT, Markdown | XLSX, XLS | OCR on images embedded in documents |
"Windows protected your PC": That's SmartScreen reacting to an unsigned build. Click "More info" then "Run anyway". The build is open source; code signing is on the roadmap.
Linux says a WebKit library is missing: Install the runtime WebKitGTK package (on Ubuntu/Lubuntu 24.04: sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 xdg-utils). That is the Linux equivalent of WebView2.
The first launch is downloading for a while: That's the one-time setup of the local Python environment. It only happens once, and every launch after is instant and offline.
AI cleanup says the key was rejected (401): The key is valid for a provider, not for "any API". In Diagnostics, set Provider to match the key (DeepSeek, Groq, OpenRouter, …) then Test. A DeepSeek key sent to OpenAI will always 401. Unambiguous prefixes (sk-ant-, gsk_, sk-or-, AIza, xai-, pplx-) switch the provider automatically; OpenAI and DeepSeek both start with sk-, so those you pick yourself.
A conversion finished with a warning or looks empty: Open the diagnostics panel. It tells you what's installed and healthy and what went wrong, so you get a clear next step instead of a silent empty file.
Where are my converted files? In the output folder shown in the app. For batch jobs you pick the folder up front.
Anything else: Open an issue. Bug reports genuinely help.
- MCP server, so Claude Code and other agents can convert documents through MDFlux directly
- CLI for scripted, headless conversion in pipelines and CI
- macOS build (arm64 and Intel)
- Code signing, to remove the SmartScreen warning
- More OCR languages and tuning presets
The full list lives in ROADMAP.md. Open an issue if you want to shape it.
MDFlux is a Tauri 2 (Rust) shell around a Python sidecar (MarkItDown + OCR + audio), with a Svelte 5 front end. You'll need Node 20+, Rust (stable), and the Tauri prerequisites for your OS; then clone it, run npm install, and npm run tauri dev. See CONTRIBUTING.md for build steps and docs/cross-platform/setup-ubuntu.md for Linux. Optional devenv setup is planned for contributors who want a pinned shell.
Contributions are genuinely welcome. Honestly, it's the main reason I'm open-sourcing this. Bug reports, ideas, code, and testing on different hardware all help.
Start with a good first issue, and see CONTRIBUTING.md to get a dev build running. Commits use a DCO sign-off (git commit -s). Be kind; we follow a Code of Conduct.
MDFlux is free and MIT-licensed. If it saves you time, supporting it goes straight into the roadmap above: the macOS build, code signing, and the MCP server and CLI.
And starring the repo is free, which helps more than you'd think.
MIT, copyright 2026 ibrahimqureshae. Free to use, modify, and distribute. See LICENSE.
