> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/markitdown/llms.txt
> Use this file to discover all available pages before exploring further.

# MarkItDown

> Main class for converting documents to Markdown

The `MarkItDown` class is the primary interface for converting various document formats to Markdown. It manages converter registration, file type detection, and the conversion process.

## Constructor

```python theme={null}
MarkItDown(
    *,
    enable_builtins: Union[None, bool] = None,
    enable_plugins: Union[None, bool] = None,
    **kwargs
)
```

Create a new MarkItDown instance.

<ParamField path="enable_builtins" type="bool | None" default="True">
  Enable built-in converters. When `None` or `True`, built-in converters are automatically registered.
</ParamField>

<ParamField path="enable_plugins" type="bool | None" default="False">
  Enable plugin converters. When `True`, converters from installed plugins are registered.
</ParamField>

<ParamField path="requests_session" type="requests.Session">
  Custom requests session for HTTP operations. If not provided, a default session is created with appropriate Accept headers.
</ParamField>

<ParamField path="llm_client" type="Any">
  LLM client instance for converters that support AI-powered conversion.
</ParamField>

<ParamField path="llm_model" type="str">
  Model name to use with the LLM client.
</ParamField>

<ParamField path="llm_prompt" type="str">
  Custom prompt to use with LLM-based converters.
</ParamField>

<ParamField path="exiftool_path" type="str">
  Path to the exiftool binary for image metadata extraction. If not provided, searches common system paths.
</ParamField>

<ParamField path="style_map" type="str">
  Custom style map for DOCX conversion.
</ParamField>

<ParamField path="docintel_endpoint" type="str">
  Azure Document Intelligence endpoint URL. When provided, enables the Document Intelligence converter.
</ParamField>

<ParamField path="docintel_credential" type="Any">
  Credentials for Azure Document Intelligence.
</ParamField>

<ParamField path="docintel_file_types" type="list">
  File types to process with Document Intelligence.
</ParamField>

<ParamField path="docintel_api_version" type="str">
  API version for Document Intelligence service.
</ParamField>

### Example

```python theme={null}
from markitdown import MarkItDown

# Basic usage with defaults
md = MarkItDown()

# With custom configuration
md = MarkItDown(
    enable_builtins=True,
    enable_plugins=False,
    exiftool_path="/usr/local/bin/exiftool"
)

# With Azure Document Intelligence
md = MarkItDown(
    docintel_endpoint="https://your-resource.cognitiveservices.azure.com/",
    docintel_credential=credential
)
```

## Methods

### convert()

```python theme={null}
def convert(
    source: Union[str, requests.Response, Path, BinaryIO],
    *,
    stream_info: Optional[StreamInfo] = None,
    **kwargs: Any
) -> DocumentConverterResult
```

Convert a document from various source types to Markdown.

<ParamField path="source" type="str | requests.Response | Path | BinaryIO" required>
  The source to convert. Can be:

  * Local file path (str or Path)
  * URL string (http\://, https\://, file://, data://)
  * requests.Response object
  * Binary file-like object (BinaryIO)
</ParamField>

<ParamField path="stream_info" type="StreamInfo">
  Optional metadata about the source. If not provided, MarkItDown attempts to infer it.
</ParamField>

<ResponseField name="result" type="DocumentConverterResult">
  The conversion result containing the Markdown text and optional metadata.
</ResponseField>

#### Example

```python theme={null}
# Convert local file
result = md.convert("document.pdf")
print(result.markdown)

# Convert URL
result = md.convert("https://example.com/file.docx")

# Convert with explicit stream info
from markitdown import StreamInfo
result = md.convert(
    "file.txt",
    stream_info=StreamInfo(charset="utf-8", mimetype="text/plain")
)

# Convert binary stream
with open("file.pdf", "rb") as f:
    result = md.convert(f)
```

### convert\_local()

```python theme={null}
def convert_local(
    path: Union[str, Path],
    *,
    stream_info: Optional[StreamInfo] = None,
    file_extension: Optional[str] = None,  # Deprecated
    url: Optional[str] = None,  # Deprecated
    **kwargs: Any
) -> DocumentConverterResult
```

Convert a local file to Markdown.

<ParamField path="path" type="str | Path" required>
  Path to the local file to convert.
</ParamField>

<ParamField path="stream_info" type="StreamInfo">
  Optional metadata about the file.
</ParamField>

<ResponseField name="result" type="DocumentConverterResult">
  The conversion result.
</ResponseField>

#### Example

```python theme={null}
result = md.convert_local("/path/to/document.docx")
print(f"Title: {result.title}")
print(result.markdown)
```

### convert\_stream()

```python theme={null}
def convert_stream(
    stream: BinaryIO,
    *,
    stream_info: Optional[StreamInfo] = None,
    file_extension: Optional[str] = None,  # Deprecated
    url: Optional[str] = None,  # Deprecated
    **kwargs: Any
) -> DocumentConverterResult
```

Convert a binary stream to Markdown.

<ParamField path="stream" type="BinaryIO" required>
  Binary file-like object to convert. Must support read() method. If not seekable, the stream is loaded into memory.
</ParamField>

<ParamField path="stream_info" type="StreamInfo">
  Optional metadata about the stream. Used for format detection.
</ParamField>

<ResponseField name="result" type="DocumentConverterResult">
  The conversion result.
</ResponseField>

#### Example

```python theme={null}
import io

# Convert in-memory bytes
data = b"PDF content..."
stream = io.BytesIO(data)
result = md.convert_stream(stream)

# With stream info
from markitdown import StreamInfo
result = md.convert_stream(
    stream,
    stream_info=StreamInfo(extension=".pdf", mimetype="application/pdf")
)
```

### convert\_url()

```python theme={null}
def convert_url(
    url: str,
    *,
    stream_info: Optional[StreamInfo] = None,
    file_extension: Optional[str] = None,
    mock_url: Optional[str] = None,
    **kwargs: Any
) -> DocumentConverterResult
```

Convert a URL to Markdown. This is an alias for `convert_uri()`.

<ParamField path="url" type="str" required>
  URL to convert (http\://, https\://, file://, or data://).
</ParamField>

<ParamField path="stream_info" type="StreamInfo">
  Optional metadata override.
</ParamField>

<ParamField path="mock_url" type="str">
  Pretend the content came from this URL instead (for converter routing).
</ParamField>

<ResponseField name="result" type="DocumentConverterResult">
  The conversion result.
</ResponseField>

#### Example

```python theme={null}
# Convert web page
result = md.convert_url("https://wikipedia.org/wiki/Python")

# Convert file URI
result = md.convert_url("file:///path/to/document.pdf")

# Convert data URI
result = md.convert_url("data:text/plain;base64,SGVsbG8gV29ybGQ=")
```

### convert\_uri()

```python theme={null}
def convert_uri(
    uri: str,
    *,
    stream_info: Optional[StreamInfo] = None,
    file_extension: Optional[str] = None,
    mock_url: Optional[str] = None,
    **kwargs: Any
) -> DocumentConverterResult
```

Convert a URI to Markdown. Supports http\://, https\://, file://, and data:// schemes.

<ParamField path="uri" type="str" required>
  URI to convert. Supported schemes:

  * `http://` and `https://`: Fetches content via HTTP
  * `file://`: Reads local file
  * `data://`: Decodes data URI
</ParamField>

<ParamField path="stream_info" type="StreamInfo">
  Optional metadata override.
</ParamField>

<ParamField path="mock_url" type="str">
  Mock the request as if it came from a different URL.
</ParamField>

<ResponseField name="result" type="DocumentConverterResult">
  The conversion result.
</ResponseField>

#### Example

```python theme={null}
# HTTP URI
result = md.convert_uri("https://example.com/doc.pdf")

# File URI
result = md.convert_uri("file:///home/user/document.docx")

# Data URI
result = md.convert_uri(
    "data:text/html;charset=utf-8,%3Ch1%3EHello%3C%2Fh1%3E"
)
```

### convert\_response()

```python theme={null}
def convert_response(
    response: requests.Response,
    *,
    stream_info: Optional[StreamInfo] = None,
    file_extension: Optional[str] = None,
    url: Optional[str] = None,
    **kwargs: Any
) -> DocumentConverterResult
```

Convert an HTTP response to Markdown.

<ParamField path="response" type="requests.Response" required>
  HTTP response object from the requests library.
</ParamField>

<ParamField path="stream_info" type="StreamInfo">
  Optional metadata override. By default, metadata is extracted from response headers.
</ParamField>

<ResponseField name="result" type="DocumentConverterResult">
  The conversion result.
</ResponseField>

#### Example

```python theme={null}
import requests

response = requests.get("https://example.com/document.pdf")
result = md.convert_response(response)
print(result.markdown)
```

### register\_converter()

```python theme={null}
def register_converter(
    converter: DocumentConverter,
    *,
    priority: float = PRIORITY_SPECIFIC_FILE_FORMAT
) -> None
```

Register a custom document converter.

<ParamField path="converter" type="DocumentConverter" required>
  The converter instance to register.
</ParamField>

<ParamField path="priority" type="float" default="0.0">
  Converter priority. Lower values are tried first. Use:

  * `PRIORITY_SPECIFIC_FILE_FORMAT` (0.0) for specific formats
  * `PRIORITY_GENERIC_FILE_FORMAT` (10.0) for generic/catch-all converters
</ParamField>

#### Example

```python theme={null}
from markitdown import MarkItDown, DocumentConverter, PRIORITY_SPECIFIC_FILE_FORMAT

class MyCustomConverter(DocumentConverter):
    def accepts(self, file_stream, stream_info, **kwargs):
        return stream_info.extension == ".custom"
    
    def convert(self, file_stream, stream_info, **kwargs):
        # Conversion logic
        return DocumentConverterResult(markdown="# Custom content")

md = MarkItDown()
md.register_converter(
    MyCustomConverter(),
    priority=PRIORITY_SPECIFIC_FILE_FORMAT
)
```

### enable\_builtins()

```python theme={null}
def enable_builtins(**kwargs) -> None
```

Enable and register built-in converters. Built-in converters are enabled by default. This method should only be called once if built-ins were initially disabled.

<ParamField path="kwargs" type="dict">
  Configuration options passed to converters (llm\_client, exiftool\_path, etc.).
</ParamField>

#### Example

```python theme={null}
# Create instance with builtins disabled
md = MarkItDown(enable_builtins=False)

# Enable later with configuration
md.enable_builtins(
    exiftool_path="/usr/local/bin/exiftool",
    llm_client=my_llm_client
)
```

### enable\_plugins()

```python theme={null}
def enable_plugins(**kwargs) -> None
```

Enable and register converters provided by installed plugins. Plugins are disabled by default. This method should only be called once if plugins were initially disabled.

<ParamField path="kwargs" type="dict">
  Configuration options passed to plugin converters.
</ParamField>

#### Example

```python theme={null}
# Create instance with plugins disabled
md = MarkItDown(enable_plugins=False)

# Enable later
md.enable_plugins()
```

## Constants

### PRIORITY\_SPECIFIC\_FILE\_FORMAT

```python theme={null}
PRIORITY_SPECIFIC_FILE_FORMAT = 0.0
```

Priority value for converters that handle specific file formats (e.g., .docx, .pdf, .xlsx) or specific websites (e.g., Wikipedia, YouTube).

### PRIORITY\_GENERIC\_FILE\_FORMAT

```python theme={null}
PRIORITY_GENERIC_FILE_FORMAT = 10.0
```

Priority value for near catch-all converters that handle generic mimetypes (e.g., text/\*, application/zip, text/html).

## Built-in Converters

When `enable_builtins=True` (default), the following converters are automatically registered:

* **PlainTextConverter** - Plain text files (priority 10.0)
* **HtmlConverter** - HTML documents (priority 10.0)
* **ZipConverter** - ZIP archives (priority 10.0)
* **RssConverter** - RSS feeds
* **WikipediaConverter** - Wikipedia pages
* **YouTubeConverter** - YouTube videos
* **BingSerpConverter** - Bing search results
* **DocxConverter** - Microsoft Word documents
* **XlsxConverter** - Excel spreadsheets (.xlsx)
* **XlsConverter** - Excel spreadsheets (.xls)
* **PptxConverter** - PowerPoint presentations
* **PdfConverter** - PDF documents
* **ImageConverter** - Image files with OCR
* **AudioConverter** - Audio files with transcription
* **IpynbConverter** - Jupyter notebooks
* **OutlookMsgConverter** - Outlook email messages
* **EpubConverter** - EPUB ebooks
* **CsvConverter** - CSV files
* **DocumentIntelligenceConverter** - Azure Document Intelligence (when endpoint provided)

## Error Handling

The `convert()` methods may raise the following exceptions:

* `FileConversionException` - Converter attempted conversion but failed
* `UnsupportedFormatException` - No converter can handle the format
* `MissingDependencyException` - Required dependency not installed

```python theme={null}
from markitdown import MarkItDown, UnsupportedFormatException

md = MarkItDown()

try:
    result = md.convert("document.xyz")
except UnsupportedFormatException:
    print("This file format is not supported")
```