references/migration.md
Migration and Release Notes
This skill targets MarkItDown 0.1.8. The timeline below summarizes changes that affect user code and operational guidance.
Release Timeline
0.1.0 — March 22, 2025
Major architecture release:
- Optional dependency feature groups introduced
- Plugin architecture introduced
- Conversions moved to in-memory streams; temporary files removed
- EPUB support added
- CLI extension, MIME, and charset hints added
--keep-data-urisadded
Breaking changes:
- Install
[all]for behavior comparable to earlier all-in-one installs. convert_stream()now requires a binary stream.DocumentConverterimplementations now receive binary streams plusStreamInfo, not file paths.
0.1.1 — March 25, 2025
convert_url()renamed toconvert_uri().file:anddata:URI handling added.convert_url()retained as a compatibility alias.
0.1.2 — May 28, 2025
- DOCX math-equation rendering
- Dedicated CSV-to-Markdown conversion
- XML/OMML parsing switched to
defusedxml - Document Intelligence credential/API-version improvements
- Streamable HTTP MCP support
- YouTube transcript fixes
- Python requirement updated to 3.10+
0.1.3 — August 26, 2025
- Safer ExifTool handling, requiring version 12.24 or later
- MCP plugin enablement through
MARKITDOWN_ENABLE_PLUGINS - DOCX linked-image fixes
- Document Intelligence HTML type handling
- Custom LLM prompt forwarding fix
- Additional HTML/PPTX robustness
0.1.4 — December 1, 2025
Security maintenance release:
- Mammoth updated to address CVE-2025-11849
pdfminer.sixupdated to address GHSA-wf5f-4jwr-ppcp
0.1.5 — February 20, 2026
- Better aligned and wide PDF tables
- Partially numbered PDF-list fix
text/markdownadded to the HTTP Accept header- Windows ONNX Runtime pin removed
0.1.6 — May 26, 2026
- Official OCR layer/plugin for embedded images and scanned PDFs
- PDF page cleanup to fix linear memory growth
- Deeply nested HTML recursion fix
- Azure Content Understanding converter
- Expanded security guidance for broad I/O and MCP binding
0.1.7 and 0.1.8 — maintenance through September 21, 2026
- Python supports >=3.10,<3.15.
- Document Intelligence defers API version selection to its SDK instead of hardcoding the old preview.
- CU uses the SDK
to_llm_input()helper and requiresazure-ai-contentunderstanding>=1.2.0b1; see the preview-default caveat incloud_and_ocr.md. - CLI cloud endpoints can come from
MARKITDOWN_DOCINTEL_ENDPOINTandMARKITDOWN_CU_ENDPOINT; stdin is buffered before detection. - CSV preserves wider rows and CR-only lines; notebook BOM/headings, RSS/Atom links/content, and duplicate ZIP member handling improved.
markitdown-ocr==0.1.1uses core Office image hooks and needs core >=0.1.8.markitdown-mcp==0.0.1a7uses MCP SDK 2.x.- URI schemes are case-insensitive;
file:rejects UNC/device paths. Local path authorization is still the caller's responsibility.
Upgrade Installation
Create a clean environment for the comparison:
uv venv --python 3.12 .venv-markitdown
source .venv-markitdown/bin/activate
uv pip install "markitdown[all]==0.1.8"
Do not test a migration in an environment that still contains unknown third-party plugins.
Code Replacements
Result content
Old/compatibility:
content = result.text_content
Current:
content = result.markdown
text_content still works in 0.1.8 but is explicitly documented in source as a soft-deprecated alias.
Local conversion
Broad:
result = converter.convert(user_value)
Narrow local path:
result = converter.convert_local(validated_path)
Use convert_stream() for validated uploaded bytes and convert_response() after an application-controlled download.
Streams
Old:
from io import StringIO
result = converter.convert_stream(StringIO("text"))
Current:
from io import BytesIO
from markitdown import StreamInfo
result = converter.convert_stream(
BytesIO(b"text"),
stream_info=StreamInfo(
extension=".txt",
mimetype="text/plain",
charset="utf-8",
),
)
URI API
Old:
result = converter.convert_url(uri)
Current:
result = converter.convert_uri(validated_uri)
Prefer caller-controlled fetching plus convert_response() for HTTP(S).
Hints
Legacy:
result = converter.convert_stream(stream, file_extension=".pdf")
Current:
from markitdown import StreamInfo
result = converter.convert_stream(
stream,
stream_info=StreamInfo(
extension=".pdf",
mimetype="application/pdf",
filename="upload.pdf",
),
)
The legacy file_extension/url parameters still exist but are marked for migration in source.
Custom Converter Migration
Pre-0.1 converter:
class OldConverter(DocumentConverter):
def convert(self, file_path):
...
0.1.x converter:
from typing import Any, BinaryIO
from markitdown import DocumentConverter, DocumentConverterResult, StreamInfo
class CurrentConverter(DocumentConverter):
def accepts(
self,
file_stream: BinaryIO,
stream_info: StreamInfo,
**kwargs: Any,
) -> bool:
...
def convert(
self,
file_stream: BinaryIO,
stream_info: StreamInfo,
**kwargs: Any,
) -> DocumentConverterResult:
return DocumentConverterResult(markdown="...")
If accepts() peeks at bytes, restore the original stream position before returning.
Plugin Packaging Migration
Outdated entry-point group:
[project.entry-points."markitdown.plugins"]
Current group:
[project.entry-points."markitdown.plugin"]
example = "example_markitdown_plugin"
The plugin module must export:
__plugin_interface_version__ = 1
def register_converters(markitdown, **kwargs):
...
Use pyproject.toml; old setup.py-only examples are no longer the preferred packaging pattern.
Installation Guidance Migration
Outdated:
uv pip install markitdown
uv pip install "markitdown[all]"
Repository-standard reproducible install:
uv pip install "markitdown[all]==0.1.8"
The base package no longer implies every format dependency. Select an extra or [all].
OCR Guidance Migration
Remove these stale claims:
- "Built-in PDF conversion uses Tesseract"
- "All images are OCR'd locally"
- "GIF and WebP are handled by the built-in image converter"
Current behavior:
- Built-in PDF extracts an existing text layer.
- Built-in JPEG/PNG conversion extracts metadata and optionally requests an LLM description.
markitdown-ocr==0.1.1uses an external vision-capable client for embedded images and scanned-PDF page fallback.- Azure Document Intelligence and Content Understanding provide cloud OCR/extraction.
The official OCR plugin README's --llm-client/--llm-model CLI example is not accepted by the 0.1.8 core CLI parser. Configure the plugin in Python.
Azure Migration
Current constructors accept explicit credentials:
MarkItDown(
docintel_endpoint="https://...",
docintel_credential=credential,
)
MarkItDown(
cu_endpoint="https://...",
cu_credential=credential,
)
Without an explicit credential, the 0.1.8 converters use the named AZURE_API_KEY if present and otherwise DefaultAzureCredential.
Do not rely on undocumented variable names such as AZURE_DOCUMENT_INTELLIGENCE_KEY for these constructors.
Content Understanding is new in 0.1.6:
from markitdown import MarkItDown
converter = MarkItDown(
cu_endpoint="https://...",
cu_analyzer_id="optional-custom-analyzer",
)
Security Migration
Replace:
- User-controlled
convert(value)calls - Broad URI access
- Automatic plugin enablement
- Undisclosed LLM/cloud fallback
- Secrets embedded in examples
- MCP binding to non-local interfaces
With:
- Narrow conversion APIs
- Path and destination allowlists
- Explicit size/time/resource limits
- Reviewed, pinned, opt-in plugins
- User-approved external processing
- Named credentials through secure provider configuration
- STDIO or localhost-only MCP in a sandbox
Regression Checklist
- [ ] Install 0.1.8 in a clean environment
- [ ] Replace
.text_contentwith.markdown - [ ] Replace text streams with binary streams
- [ ] Replace
convert_url()withconvert_uri()or controlled fetch - [ ] Update custom converter signatures
- [ ] Update plugin entry-point group
- [ ] Pin format extras
- [ ] Test PDF tables and multi-column reading order
- [ ] Test DOCX math and linked images
- [ ] Test PPTX grouped shapes and notes
- [ ] Confirm plugins remain disabled by default
- [ ] Confirm no conversion unexpectedly calls network/cloud
- [ ] Compare semantic output on a representative corpus
Sources
- Releases: https://github.com/microsoft/markitdown/releases
- 0.1.0 migration notes: https://github.com/microsoft/markitdown/releases/tag/v0.1.0
- 0.1.6 release: https://github.com/microsoft/markitdown/releases/tag/v0.1.6
- 0.1.8 release: https://github.com/microsoft/markitdown/releases/tag/v0.1.8