Install & Compatibility
Where this runs
tested against v0.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 2.298s · 322.2MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 9.7s · import 1.517s · 418MB
291MB installed
● package 291MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MarkItDown
✓ from markitdown import MarkItDown
Initializes MarkItDown and demonstrates conversion using a data URI. It also includes commented-out code for converting a local file, highlighting the need for correct optional dependency installation.
from markitdown import MarkItDown
import base64
markitdown = MarkItDown()
# Convert a data URI containing plain text to Markdown
text_content = "Hello from MarkItDown! This is a test.\n\n- Item 1\n- Item 2"
base64_content = base64.b64encode(text_content.encode('utf-8')).decode('utf-8')
data_uri = f"data:text/plain;base64,{base64_content}"
result = markitdown.convert_uri(data_uri)
print(f"Converted Markdown:\n{result.markdown}")
# Example of how you would convert a local file (replace with an actual path)
# try:
# result = markitdown.convert_uri("file:///path/to/your/document.docx")
# print(f"Converted DOCX:\n{result.markdown}")
# except Exception as e:
# print(f"Could not convert DOCX: {e} (Ensure you have installed markitdown[docx] and the file exists)")
Debug
Known issues
gotchaStarting with v0.1.0, MarkItDown introduced a plugin-based architecture and optional dependency groups (e.g., `[docx]`, `[pdf]`, `[all]`). If you only `pip install markitdown`, you may lack converters for specific file types.fixInstall with the specific feature groups needed, e.g., `pip install markitdown[docx]` for DOCX support, or `pip install markitdown[all]` for all converters.
affects: >=0.1.0
deprecatedThe `convert_url` method was renamed to `convert_uri` in v0.1.1. While `convert_url` remains an alias for backward compatibility, new code should prefer `convert_uri`.fixUpdate calls from `markitdown.convert_url(...)` to `markitdown.convert_uri(...)`.
affects: >=0.1.1
gotchaThe `onnxruntime` dependency has seen several changes (pinned in v0.1.3 on Windows, removed upper bound in v0.1.5). Users might encounter `onnxruntime` version conflicts, especially in complex environments.fixIf `onnxruntime` issues arise, try upgrading/downgrading it, or install `markitdown` in a dedicated virtual environment. Check the `onnxruntime` GitHub for compatibility notes if problems persist.
affects: All versions >=0.1.3
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'markitdown'
The 'markitdown' package is either not installed, or installed in a different Python environment than the one currently active, or there is a Python version incompatibility (e.g., trying to use it with Python versions older than 3.10).
fixEnsure 'markitdown' is installed correctly within your active Python environment using `pip install 'markitdown[all]'` and verify that your Python version is 3.10 or higher.
MissingDependencyException with message: PdfConverter recognized the input as a potential .pdf file, but the dependencies needed to read .pdf files have not been installed. To resolve this error, include the optional dependency [pdf] or [all] when installing MarkItDown.
While the core 'markitdown' library is installed, the specific optional dependencies required for converting certain file formats (like PDF, DOCX, XLSX) were not included during the initial installation.
fixReinstall 'markitdown' with the `[all]` extra to include all optional dependencies (`pip install 'markitdown[all]'`) or explicitly install the dependencies for the specific format you need (e.g., `pip install 'markitdown[pdf]'`).
UnsupportedFormatException: Could not convert 'file.xml' to Markdown. The formats ['.xml', '.xml', '.docbook', '.qtl', '.rng'] are not supported.
The 'markitdown' library was asked to convert a file type (e.g., an older .doc file, or a less common XML variant) for which it does not have a registered converter or explicitly does not support.
fixRefer to the 'markitdown' documentation to confirm supported file formats. If the format is generally supported (e.g., .docx, .pdf), ensure all necessary optional dependencies are installed. If it's truly unsupported, consider converting the document to a supported format first or implementing a custom converter if the library's architecture allows.
The `convert_stream()` method now requires a binary file-like object (e.g., a file opened in binary mode, or an `io.BytesIO` object).
In 'markitdown' versions 0.1.0 and later, the `convert_stream()` method was updated to strictly require a binary file-like object, unlike previous versions (0.0.x) that also accepted text file-like objects, which is a breaking change.
fixWhen using `convert_stream()`, ensure the input stream is opened in binary mode (e.g., `with open('file.pdf', 'rb') as f: ...`) or is an `io.BytesIO` object. Upgrade
Version history
0.1.7latest on PyPI · released Jul 29, 2026
Audit
Dependencies
mammothoptionalRequired for DOCX conversion.
pdfminer.sixoptionalRequired for PDF conversion.
onnxruntimeoptionalPotentially used for some ML-based parsing components; dependency management has been volatile.