MarkItDown
MarkItDown quickstart: convert one file and check the result
Install a focused MarkItDown environment, use the CLI and Python API, and diagnose missing dependencies separately from extraction-quality problems.
What you will learn
- Use one known fixture for CLI and API comparisons.
- Verify facts in the output rather than only the exit code.
- Record plugin configuration because it can change selection.
Before you start
- Basic Python and command-line usage
- A non-sensitive document whose contents you can verify
Use the chapter checklist to explain and verify this part of a document ingestion workflow.
Key takeaways
- Use one known fixture for CLI and API comparisons.
- Verify facts in the output rather than only the exit code.
- Record plugin configuration because it can change selection.
Install for the file you actually have
The documented baseline is Python 3.10 or newer. Use a virtual environment so optional PDF and Office dependencies do not silently interact with an unrelated application. The README supports individual extras such as pdf, docx and pptx as well as an all-extras installation.
For an initial DOCX exercise, install the docx extra and prepare example.docx yourself. Package installation commands resolve the versions available when executed. After the experiment works, record the resolved package versions before sharing it as a reproducible team setup. The commands below are setup instructions, not a claim that every converter has been run here.
Use the same fixture through two interfaces
The CLI accepts an input path and an output path through -o. The Python API returns a conversion result whose markdown property contains the generated text. Use the same source file with both interfaces so any discrepancy can be investigated without changing the content or installed dependencies.
A useful acceptance check names facts rather than aesthetics: the document heading appears once, a link points to the intended address, table values stay associated with their labels, and special characters survive. Store the expected facts alongside the fixture. An empty Markdown file is a failed conversion for this exercise even if an output path exists.
Diagnose setup and content problems separately
An import error or a missing optional dependency is an environment problem. A completed conversion with an absent table or scrambled reading order is a content-quality problem. Capture the first exception and the selected file type before changing packages; changing several extras and plugins at once makes the cause harder to identify.
Third-party plugins are disabled by default according to the README. List installed plugins before enabling them, then rerun the same fixture. A plugin may change converter selection, so save the plugin configuration with the result instead of treating it as an invisible enhancement.
Implementation steps
- 1
Create and activate a Python virtual environment.
- 2
Install the docx extra and prepare example.docx.
- 3
Convert with -o and inspect the Markdown.
- 4
Record package versions and compare the API output.
Copy-ready example
python -m venv .venv
# POSIX shell; on Windows activate the environment with its PowerShell script.
. .venv/bin/activate
python -m pip install "markitdown[docx]"
markitdown example.docx -o example.md
python -m pip freezeFrequently asked questions
Should I install every extra?
Install the formats you need first. The all extra is convenient for broad evaluation but brings a larger dependency set.
Why did enabling a plugin change the output?
Plugins can register additional converters and priorities. Repeat the same fixture with a recorded plugin configuration to isolate the change.
Sources
- Pinned sourceSource checked 2026-09-07
- Core dispatcherSource checked 2026-09-07
- Plain-text converterSource checked 2026-09-07
- Public exportsSource checked 2026-09-07