MarkItDown 0.1.8 API Reference

Verified against the v0.1.8 source tag and installed package on October 1, 2026.

Public Imports

from markitdown import (
    DocumentConverter,
    DocumentConverterResult,
    FileConversionException,
    MarkItDown,
    MissingDependencyException,
    PRIORITY_GENERIC_FILE_FORMAT,
    PRIORITY_SPECIFIC_FILE_FORMAT,
    StreamInfo,
    UnsupportedFormatException,
)

Azure file-type enums are exported from markitdown.converters:

from markitdown.converters import (
    ContentUnderstandingFileType,
    DocumentIntelligenceFileType,
)

MarkItDown

Constructor

MarkItDown(
    *,
    enable_builtins: bool | None = None,
    enable_plugins: bool | None = None,
    **kwargs,
)

Built-in converters are enabled by default. Third-party plugins are disabled by default.

Recognized constructor keywords include:

The public signature uses **kwargs; spell these names exactly. Unknown names can be silently ignored: there is no cu_api_version option. docintel_api_version=None delegates to the installed Azure SDK default. See cloud_and_ocr.md for the tested SDK versions and network contracts.

Conversion methods

convert()

convert(
    source: str | Path | requests.Response | BinaryIO,
    *,
    stream_info: StreamInfo | None = None,
    **kwargs,
) -> DocumentConverterResult

Dispatch rules:

• str with a parsed http:, https:, file:, or data: scheme (case-insensitive) → convert_uri()
• other str or Path → convert_local()
• requests.Response → convert_response()
• binary file-like object → convert_stream()
• text stream → TypeError

This convenience method is broad. Prefer a narrower method for untrusted or application-facing inputs.

convert_local()

convert_local(
    path: str | Path,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

file_extension and url are legacy parameters; put overrides in StreamInfo.

from pathlib import Path

from markitdown import MarkItDown

source = Path("experiment.xlsx")
result = MarkItDown().convert_local(source)
Path("experiment.md").write_text(result.markdown, encoding="utf-8")

convert_stream()

convert_stream(
    stream: BinaryIO,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

Requirements and behavior:

• The stream must be binary.
• A seekable stream is preferred.
• A non-seekable stream is copied completely into an in-memory BytesIO.
• file_extension and url are legacy hints; prefer StreamInfo.

from io import BytesIO

from markitdown import MarkItDown, StreamInfo

payload = b"sample,value\ncontrol,1\ntreated,2\n"
result = MarkItDown().convert_stream(
    BytesIO(payload),
    stream_info=StreamInfo(
        extension=".csv",
        mimetype="text/csv",
        charset="utf-8",
        filename="results.csv",
    ),
)
print(result.markdown)

convert_uri()

convert_uri(
    uri: str,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    mock_url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

Supported schemes:

• file: with an empty authority or localhost
• data:
• http:
• https:

HTTP(S) conversion uses the configured requests.Session, follows Requests defaults, and then buffers the complete response in memory. It does not provide an application-level SSRF policy, download-size limit, or redirect allowlist. Validate and fetch remote resources yourself before calling convert_response().

convert_url() remains a backward-compatible alias, but new code should use convert_uri().

convert_response()

convert_response(
    response: requests.Response,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

The method derives hints from Content-Type, Content-Disposition, and the response URL, then buffers every response chunk into memory. The caller is responsible for destination validation, redirect handling, timeout, maximum size, authentication, and TLS policy.

StreamInfo

StreamInfo(
    *,
    mimetype: str | None = None,
    extension: str | None = None,
    charset: str | None = None,
    filename: str | None = None,
    local_path: str | None = None,
    url: str | None = None,
)

Examples:

pdf_info = StreamInfo(
    mimetype="application/pdf",
    extension=".pdf",
    filename="paper.pdf",
)

html_info = StreamInfo(
    mimetype="text/html",
    extension=".html",
    charset="utf-8",
    filename="article.html",
)

Hints are merged with extension, HTTP header, and Magika content-detection guesses. If a caller-supplied hint conflicts with content detection, MarkItDown may try both guesses.

DocumentConverterResult

DocumentConverterResult(
    markdown: str,
    *,
    title: str | None = None,
)

Attributes and conversions:

result = MarkItDown().convert_local("paper.pdf")
markdown = result.markdown
title = result.title

Per-conversion Options

Converter-specific values can be forwarded through a conversion call:

result = converter.convert_local(
    "page.html",
    keep_data_uris=False,
)

Common options:

Exceptions

from markitdown import (
    FileConversionException,
    MissingDependencyException,
    UnsupportedFormatException,
)

from markitdown import (
    FileConversionException,
    MarkItDown,
    MissingDependencyException,
    UnsupportedFormatException,
)

try:
    result = MarkItDown().convert_local("input.pdf")
except MissingDependencyException:
    print("Install markitdown[pdf]==0.1.8")
except UnsupportedFormatException:
    print("No converter accepted this input")
except FileConversionException as exc:
    print(f"A matching converter failed: {exc}")

Converter Registration

register_converter(
    converter: DocumentConverter,
    *,
    priority: float = PRIORITY_SPECIFIC_FILE_FORMAT,
) -> None

Lower numeric priorities run first. The built-in specific-format priority is 0.0; generic converters use 10.0. For registrations with equal priority, the most recently registered converter is attempted first.

register_page_converter() is deprecated.

Custom Converter

Version 0.1.x converters operate on binary streams and implement both accepts() and convert():

from typing import Any, BinaryIO

from markitdown import (
    DocumentConverter,
    DocumentConverterResult,
    StreamInfo,
)


class RtfConverter(DocumentConverter):
    def accepts(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> bool:
        return (stream_info.extension or "").lower() == ".rtf"

    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> DocumentConverterResult:
        raw = file_stream.read()
        # Replace this placeholder with a real, bounded RTF parser.
        return DocumentConverterResult(
            markdown=f"```text\n{raw.decode('utf-8', errors='replace')}\n```"
        )

Do not advance the stream in accepts(). If inspection is necessary, save the position with tell() and restore it with seek().

Plugin Package Contract

The plugin module exports interface version 1 and a registration function:

from markitdown import MarkItDown

__plugin_interface_version__ = 1


def register_converters(markitdown: MarkItDown, **kwargs) -> None:
    markitdown.register_converter(RtfConverter())

Register the module through pyproject.toml:

[project.entry-points."markitdown.plugin"]
example = "example_markitdown_plugin"

Inspect and install a trusted, pinned plugin, then verify discovery:

markitdown --list-plugins
markitdown --use-plugins input.rtf -o output.md

CLI Reference

markitdown [options] [filename]

If filename is omitted, MarkItDown buffers all binary stdin in memory before detection. Document Intelligence mode requires a filename; CU accepts hinted stdin.

Document Intelligence and Content Understanding are mutually exclusive in one CLI invocation.

The core 0.1.8 parser does not expose --llm-client or --llm-model. Configure image descriptions or the OCR plugin through Python.

Source Basis

• v0.1.8 package API: https://github.com/microsoft/markitdown/tree/v0.1.8/packages/markitdown/src/markitdown
• v0.1.8 CLI: https://github.com/microsoft/markitdown/blob/v0.1.8/packages/markitdown/src/markitdown/__main__.py
• v0.1.8 sample plugin: https://github.com/microsoft/markitdown/tree/v0.1.8/packages/markitdown-sample-plugin