Repository guide · overview · v2
microsoft / markitdown
“Python tool for converting files and office documents to Markdown.” — as described by its authors
- Data Processing
- Python
- MIT · open-source license
- Original repository
- microsoft/markitdown
- Source platform
- GitHub
- Repository owner / organization
- microsoft
- License
- MIT · open-source license
- Analyzed revision
- ed178952a6672abdfd35b5f9e76a80b6cefc086e
- Last verified
Source checked 2026-11-15: default branch still at the analyzed revision.
microsoft/markitdown repository overview
Terms used on this page
- Entrypoint record
- A file the analyzer marks as a place where execution can start. When it carries a __main__ guard excerpt, the file contains an if __name__ == "__main__": block and the excerpt shows what that block calls; without an excerpt, the file was flagged by its name only.
- Bounded static execution path
- A call chain reconstructed from the source code without running it, stopped after a fixed number of steps. It shows how far the code can be followed on paper, not what happens at run time.
- Unresolved boundary
- Where a static path stops because the next call goes into an external library or cannot be resolved without running the code. It marks the edge of this analysis, not a defect in the repository.
- Static relations
- Calls and imports found in the source. "External or unresolved" relations point outside the analyzed files.
- Module role
- The analyzer's label for a file, inferred from how many calls go in and out (for example core, entry/orchestration, leaf). It describes a position in the call graph, not the authors' design.
- Test-like files
- Files whose names or locations look like tests. This analysis counts them; it does not run them.
- Observed · inferred · author-claimed · unresolved
- How each statement is supported: read directly from the analyzed files; derived by the analyzer from them; stated by the repository's authors (metadata, README); or not established by this analysis.
- Verified
- Two uses on these pages. In an analyzer record ("verified provenance", "a verified entrypoint") it means the record was read directly from the analyzed files, which these guides call observed; for an entrypoint, the __main__ guard text is present. Since the analyzer fix of 2026-10-04, a file that only has an entrypoint-like name such as cli.py or main.py is recorded as inferred; guides analyzed before that still call such a file verified, and it is still only a guess about how the file is used. It does not mean the code was run or tested. "Last verified" is the date the guide last passed the lab's checks against the analysis record of the stated revision; it is not a review of the repository itself.
A Python monorepo whose GitHub description says it converts files and office documents to Markdown. It holds four packages: a core `markitdown` library, an MCP server, an OCR add-on and a sample plugin. Static call degree points to `_markitdown.py` as the core hub. Most relations are unresolved, and runtime behavior is not established.
What it is
According to its GitHub description, this is a Python tool for converting files and office documents to Markdown. Platform metadata lists Python as the primary language and MIT as the license. The listed topics include markdown, pdf, microsoft-office, openai, langchain and autogen.
Structurally, the repository is a small monorepo. Four pyproject.toml manifests sit under packages/, one each for markitdown, markitdown-mcp, markitdown-ocr and markitdown-sample-plugin.
The latest platform release is v0.1.9. Both markitdown-mcp and markitdown-ocr declare a runtime dependency on markitdown in the range >=0.1.9,<0.2.0.
Judging from the package names and entrypoints, markitdown appears to be the core converter library. The other three packages look like an MCP server wrapper, an OCR add-on and a plugin example.
How it starts
Two __main__ guards sit in library source rather than in tests: packages/markitdown/src/markitdown/__main__.py and packages/markitdown-mcp/src/markitdown_mcp/__main__.py. Both guards call a main() function.
Most other detected guards are in test modules and fixture generators. They hand their own file to pytest.main or call test helpers or a local main directly. Some guards in test_cli_vectors.py and test_module_vectors.py only switch imports.
The bounded static paths in this packet cover only the MCP entry. There, the guard calls main, which builds an argparse parser. The traced paths stop at external boundaries such as argparse.ArgumentParser and parser.add_argument.
At module level the same file references MCPServer and logging.getLogger, and both are left unresolved. For MCPServer, static analysis leaves its origin unresolved; it probably comes from the mcp dependency.
The packet contains no execution path for the core markitdown/__main__.py. How the command-line entry reaches the MarkItDown class is therefore not established here.
Structure
The analyzer's summary places 181 of the 197 files under packages/. The rest are in the root (10), .github (5) and .devcontainer (1).
Ranking modules by resolved cross-module call degree gives a rough picture of the core library:
markitdown/_markitdown.pyhas the most outgoing calls (33, with 4 incoming). It defines the largeMarkItDownclass (lines 141-861), aConverterRegistrationclass and_load_plugins, so it is the likely orchestration hub._base_converter.py(21 incoming),converters/__init__.py(20),_exceptions.py(19) and_stream_info.py(14) have no outgoing calls. They look like shared definitions, such asDocumentConverter,DocumentConverterResult,StreamInfoand the exception types.converter_utils/docx/math/omml.py(25 outgoing) andlatex_dict.py(25 incoming) appear to form a pair that translates Office math markup to LaTeX throughoMath2Latex.- Format converters such as
_xlsx_converter.pyand_pptx_converter.pyshow zero resolved incoming calls. This fits converters being registered and dispatched indirectly rather than called by name.
Dependencies and tests
Dependency records come from the four pyproject.toml files:
markitdown: recorded runtime deps includebeautifulsoup4,requests,certifi,markdownify,magika,charset-normalizeranddefusedxml. Optional deps cover specific formats and services, includingpython-pptx,mammoth,pandas,openpyxl,xlrd,lxml,pdfminer.six,pdfplumber,olefile,pydub,SpeechRecognition,youtube-transcript-apiand Azure packages.markitdown-mcp:mcp(>=2.1.1,<3.0.0) andmarkitdown.markitdown-ocr:markitdownplus PDF, Office and imaging libraries, with optionalopenai.markitdown-sample-plugin:markitdownandstriprtf.
Several optional records repeat the same name and line, and the packet does not explain why. Only some manifest types are parsed, and versions are recorded as written.
The analyzer counts 112 test or test-like files. The sampled list includes fixture documents, so not all of them are test code. Per-format test modules (CSV, DOCX, EPUB, HTML, PDF, PPTX, XLSX, ZIP and others) each contain a pytest.main guard.
What to read first
This suggested order combines the files the analyzer marked important with the most connected modules:
README.mdandLICENSE, both flagged as project-level important files.packages/markitdown/src/markitdown/__main__.py, then_markitdown.py, focusing onMarkItDown,ConverterRegistrationand_load_plugins._base_converter.py,_stream_info.pyand_exceptions.pyfor the shared types that converters build on.- One concrete converter, for example
converters/_html_converter.py(HtmlConverter), which has both incoming and outgoing calls. packages/markitdown-mcp/src/markitdown_mcp/__main__.pywithtests/test_stdio_protocols.py. Then readpackages/markitdown-sample-plugin/tests/test_sample_plugin.pyto see how a plugin is exercised.
Limits of this analysis
Of 6,816 static relations, 5,812 are external or unresolved and only 1,004 resolve locally. Most call targets are kept as text rather than linked to code.
The analysis is static only, so dynamic imports, runtime registration and dynamic dispatch are not resolved. The core includes _load_plugins, and the OCR and sample packages appear to be plugins. Which converters are active at runtime therefore cannot be established here.
Install, build and run inference is partial, and no command was verified. For that reason this asset gives no installation or run instructions.
The analyzer's own teaching notes are inconsistent. One says no bounded execution path exists, yet the packet contains several. Another names a test file as the starting point.
Under the analyzer's bounds, files over 400 kB, minified bundles and vendored directories are inventoried but not parsed.
Whether any entrypoint actually runs, and what output it produces, is not established.
What this analysis could not establish
The writing model's own notes on the analysis record. Identifiers such as lim_3, exec_* or claim_… name records of that analysis; the claims table cites the same records.
- One of the analyzer's teaching claims states that no bounded static execution path is available, but the packet contains execution-path records and the analyzer reports 155 bounded execution paths.
- The analyzer names different starting points: its repository summary points to the MCP __main__.py, while one of its teaching claims points to a test file (test_cli_vectors.py).
- The control flow of packages/markitdown/src/markitdown/__main__.py is not covered by any execution path in the packet.
- Names of the optional-dependency extras in packages/markitdown/pyproject.toml are not in the packet, and several records are duplicated.
- How markitdown-ocr and markitdown-sample-plugin are discovered and registered at runtime is not established; only file names and import relations hint at a plugin mechanism.
- The certifi constraint (>=2026.10.19) and other version strings are recorded as written and were not checked.
Claims and evidence — 36 claims, 36 supported by an independent verifier
Every statement above is a claim that cites grounding IDs from the analysis. IDs are internal to the analysis run; the columns show what each claim rests on and how strong that ground is.
Every substantive statement above is a claim bound to grounding IDs of the analyzed revision. Global grounding IDs are namespaced by the analysis run.
| Claim | Epistemic status | Verifier | Grounding (global IDs) |
|---|---|---|---|
| c1 The GitHub description says the project is a Python tool for converting files and office documents to Markdown. | author_claimed | supported | analysis_5d9c9ae9a129bff5:meta_description |
| c2 Platform metadata lists Python as the primary language and MIT as the license, with topics including markdown, pdf, microsoft-office, openai, langchain and autogen. | observed | supported | analysis_5d9c9ae9a129bff5:meta_primary_language, analysis_5d9c9ae9a129bff5:meta_license, analysis_5d9c9ae9a129bff5:meta_topics |
| c3 The repository has four pyproject.toml manifests under packages/, for markitdown, markitdown-mcp, markitdown-ocr and markitdown-sample-plugin. | observed | supported | analysis_5d9c9ae9a129bff5:ev_manifest_1, analysis_5d9c9ae9a129bff5:dep_1, analysis_5d9c9ae9a129bff5:dep_3, analysis_5d9c9ae9a129bff5:dep_14, analysis_5d9c9ae9a129bff5:dep_16 |
| c4 The latest platform release is v0.1.9, and markitdown-mcp and markitdown-ocr both require markitdown >=0.1.9,<0.2.0 at runtime. | observed | supported | analysis_5d9c9ae9a129bff5:meta_latest_release, analysis_5d9c9ae9a129bff5:dep_2, analysis_5d9c9ae9a129bff5:dep_3 |
| c5 From package names and entrypoints, markitdown appears to be the core converter library, while the other packages look like an MCP server wrapper, an OCR add-on and a plugin example. | inferred | supported | analysis_5d9c9ae9a129bff5:important_6, analysis_5d9c9ae9a129bff5:important_3, analysis_5d9c9ae9a129bff5:important_5, analysis_5d9c9ae9a129bff5:dep_3 |
| c6 Non-test __main__ guards exist in packages/markitdown/src/markitdown/__main__.py and packages/markitdown-mcp/src/markitdown_mcp/__main__.py, and both call main(). | observed | supported | analysis_5d9c9ae9a129bff5:py_entry_d19b256901ab, analysis_5d9c9ae9a129bff5:py_entry_2f852a8015d4 |
| c7 Most other detected __main__ guards are in test modules and fixture generators and call pytest.main on their own file, test helpers or a local main; some guards in test_cli_vectors.py and test_module_vectors.py only switch imports. | observed | supported | analysis_5d9c9ae9a129bff5:py_entry_f44307e3b0be, analysis_5d9c9ae9a129bff5:py_entry_a63fdf323f3b, analysis_5d9c9ae9a129bff5:py_entry_157267349a98, analysis_5d9c9ae9a129bff5:py_entry_007b88c947c9, analysis_5d9c9ae9a129bff5:py_entry_791d98438517 |
| c8 Static paths from the MCP entry go from the guard to main, which reaches argparse.ArgumentParser and parser.add_argument, where the paths stop at unresolved boundaries. | inferred | supported | analysis_5d9c9ae9a129bff5:exec_11e5ff5e359f, analysis_5d9c9ae9a129bff5:exec_51ee1388edd7 |
| c9 The MCP __main__ module references MCPServer and logging.getLogger as unresolved external targets, so the server object probably comes from the mcp dependency. | inferred | supported | analysis_5d9c9ae9a129bff5:exec_b68e1f5a7c8a, analysis_5d9c9ae9a129bff5:exec_67998e701fae, analysis_5d9c9ae9a129bff5:dep_1 |
| c10 No execution path for packages/markitdown/src/markitdown/__main__.py is in the packet, so how it reaches the MarkItDown class is not established. | unresolved | supported | analysis_5d9c9ae9a129bff5:py_entry_d19b256901ab, analysis_5d9c9ae9a129bff5:py_class_54565613c36d |
| c11 The analyzer summary reports 197 files, 181 of them under packages/, with 10 at the root, 5 in .github and 1 in .devcontainer. | inferred | supported | analysis_5d9c9ae9a129bff5:summary_repository |
| c12 By static cross-module call degree, _markitdown.py (33 outgoing, 4 incoming) is the likely hub; it defines MarkItDown (lines 141-861), ConverterRegistration and _load_plugins. | inferred | supported | analysis_5d9c9ae9a129bff5:role_13, analysis_5d9c9ae9a129bff5:py_class_54565613c36d, analysis_5d9c9ae9a129bff5:py_class_a5c27a19fe56, analysis_5d9c9ae9a129bff5:py_func_575e8ec2d882 |
| c13 _base_converter.py, converters/__init__.py, _exceptions.py and _stream_info.py have many incoming and no outgoing resolved calls, and look like shared definitions such as DocumentConverter, DocumentConverterResult, StreamInfo and exception types. | inferred | supported | analysis_5d9c9ae9a129bff5:role_11, analysis_5d9c9ae9a129bff5:role_22, analysis_5d9c9ae9a129bff5:role_12, analysis_5d9c9ae9a129bff5:role_14, analysis_5d9c9ae9a129bff5:py_class_b1900e6bc249, analysis_5d9c9ae9a129bff5:py_class_870f0e7b97a3, analysis_5d9c9ae9a129bff5:py_class_90b74f2e9504, analysis_5d9c9ae9a129bff5:py_class_1e5fe54ba53d |
| c14 omml.py (25 outgoing) and latex_dict.py (25 incoming) appear to form a pair that converts Office math markup to LaTeX via the oMath2Latex class. | inferred | supported | analysis_5d9c9ae9a129bff5:role_20, analysis_5d9c9ae9a129bff5:role_19, analysis_5d9c9ae9a129bff5:py_class_54034cf76a50 |
| c15 _xlsx_converter.py and _pptx_converter.py have zero resolved incoming calls, which is consistent with converters being registered and dispatched indirectly. | inferred | supported | analysis_5d9c9ae9a129bff5:role_43, analysis_5d9c9ae9a129bff5:role_39, analysis_5d9c9ae9a129bff5:py_class_b026ac93be11, analysis_5d9c9ae9a129bff5:py_class_164537a7db47 |
| c16 Dependency records come from four pyproject.toml manifests; markitdown's recorded runtime deps include beautifulsoup4, requests, certifi, markdownify, magika, charset-normalizer and defusedxml. | observed | supported | analysis_5d9c9ae9a129bff5:ev_manifest_1, analysis_5d9c9ae9a129bff5:dep_16, analysis_5d9c9ae9a129bff5:dep_17, analysis_5d9c9ae9a129bff5:dep_18, analysis_5d9c9ae9a129bff5:dep_19, analysis_5d9c9ae9a129bff5:dep_20, analysis_5d9c9ae9a129bff5:dep_21, analysis_5d9c9ae9a129bff5:dep_22 |
| c17 markitdown's optional deps include python-pptx, mammoth, pandas, openpyxl, xlrd, lxml, pdfminer.six, pdfplumber, olefile, pydub, SpeechRecognition, youtube-transcript-api and Azure packages. | observed | supported | analysis_5d9c9ae9a129bff5:dep_23, analysis_5d9c9ae9a129bff5:dep_24, analysis_5d9c9ae9a129bff5:dep_25, analysis_5d9c9ae9a129bff5:dep_26, analysis_5d9c9ae9a129bff5:dep_27, analysis_5d9c9ae9a129bff5:dep_28, analysis_5d9c9ae9a129bff5:dep_29, analysis_5d9c9ae9a129bff5:dep_30, analysis_5d9c9ae9a129bff5:dep_31, analysis_5d9c9ae9a129bff5:dep_32, analysis_5d9c9ae9a129bff5:dep_33, analysis_5d9c9ae9a129bff5:dep_34, analysis_5d9c9ae9a129bff5:dep_35, analysis_5d9c9ae9a129bff5:dep_36, analysis_5d9c9ae9a129bff5:dep_37 |
| c18 markitdown-mcp depends on mcp >=2.1.1,<3.0.0 and on markitdown. | observed | supported | analysis_5d9c9ae9a129bff5:dep_1, analysis_5d9c9ae9a129bff5:dep_2 |
| c19 markitdown-ocr depends on markitdown, pdfminer.six, pdfplumber, PyMuPDF, mammoth, python-docx, python-pptx, pandas, openpyxl and Pillow, with openai as an optional dependency. | observed | supported | analysis_5d9c9ae9a129bff5:dep_3, analysis_5d9c9ae9a129bff5:dep_4, analysis_5d9c9ae9a129bff5:dep_5, analysis_5d9c9ae9a129bff5:dep_6, analysis_5d9c9ae9a129bff5:dep_7, analysis_5d9c9ae9a129bff5:dep_8, analysis_5d9c9ae9a129bff5:dep_9, analysis_5d9c9ae9a129bff5:dep_10, analysis_5d9c9ae9a129bff5:dep_11, analysis_5d9c9ae9a129bff5:dep_12, analysis_5d9c9ae9a129bff5:dep_13 |
| c20 markitdown-sample-plugin depends on markitdown >=0.1.0a1 and striprtf. | observed | supported | analysis_5d9c9ae9a129bff5:dep_14, analysis_5d9c9ae9a129bff5:dep_15 |
| c21 Several optional records repeat the same name and line (e.g. python-pptx at line 39, azure-identity at line 53); the packet does not explain why. | inferred | supported | analysis_5d9c9ae9a129bff5:dep_23, analysis_5d9c9ae9a129bff5:dep_38, analysis_5d9c9ae9a129bff5:dep_52, analysis_5d9c9ae9a129bff5:dep_54 |
| c22 Only requirements files, package.json and pyproject.toml are parsed for dependencies; setup.py, setup.cfg, Pipfile and lock files are not, and versions are recorded as written. | observed | supported | analysis_5d9c9ae9a129bff5:lim_3a |
| c23 The analyzer counts 112 test or test-like files; the sampled list includes fixture documents, so not all are test code. | inferred | supported | analysis_5d9c9ae9a129bff5:ev_tests_1 |
| c24 Per-format test modules for CSV, DOCX, EPUB, HTML, PDF, PPTX, XLSX and ZIP each contain a __main__ guard that calls pytest.main. | observed | supported | analysis_5d9c9ae9a129bff5:py_entry_6da5faf654d3, analysis_5d9c9ae9a129bff5:py_entry_e1644548438f, analysis_5d9c9ae9a129bff5:py_entry_fd2581a2a85a, analysis_5d9c9ae9a129bff5:py_entry_c1e9a0696ede, analysis_5d9c9ae9a129bff5:py_entry_d48046c8aa24, analysis_5d9c9ae9a129bff5:py_entry_f19b18e9138b, analysis_5d9c9ae9a129bff5:py_entry_fc521ad126e1, analysis_5d9c9ae9a129bff5:py_entry_98eaed3ae984 |
| c25 README.md and LICENSE are flagged by the analyzer as project-level important files. | observed | supported | analysis_5d9c9ae9a129bff5:important_1, analysis_5d9c9ae9a129bff5:important_2 |
| c26 A suggested reading order combines important files with connected modules: start at packages/markitdown/src/markitdown/__main__.py, then _markitdown.py with MarkItDown, ConverterRegistration and _load_plugins. | inferred | supported | analysis_5d9c9ae9a129bff5:important_6, analysis_5d9c9ae9a129bff5:role_13, analysis_5d9c9ae9a129bff5:py_class_54565613c36d, analysis_5d9c9ae9a129bff5:py_class_a5c27a19fe56, analysis_5d9c9ae9a129bff5:py_func_575e8ec2d882 |
| c27 Reading _base_converter.py, _stream_info.py and _exceptions.py next is suggested, because they hold shared types that many modules call into. | inferred | supported | analysis_5d9c9ae9a129bff5:role_11, analysis_5d9c9ae9a129bff5:role_14, analysis_5d9c9ae9a129bff5:role_12, analysis_5d9c9ae9a129bff5:py_class_b1900e6bc249 |
| c28 converters/_html_converter.py (HtmlConverter) has both incoming (6) and outgoing (4) calls, which makes it a reasonable concrete converter to read. | inferred | supported | analysis_5d9c9ae9a129bff5:role_31, analysis_5d9c9ae9a129bff5:py_class_048314abbf0a |
| c29 The MCP entry, its test_stdio_protocols.py test and the sample plugin test are flagged as likely entrypoints and are suggested for reading after the core. | inferred | supported | analysis_5d9c9ae9a129bff5:important_3, analysis_5d9c9ae9a129bff5:important_4, analysis_5d9c9ae9a129bff5:important_5 |
| c30 Of 6816 static relations, 5812 are external or unresolved and 1004 resolve locally. | observed | supported | analysis_5d9c9ae9a129bff5:relation_counts |
| c31 Analysis is static only, and the core has a _load_plugins function, so which converters and plugins are active at runtime cannot be established. | inferred | supported | analysis_5d9c9ae9a129bff5:lim_1, analysis_5d9c9ae9a129bff5:py_func_575e8ec2d882, analysis_5d9c9ae9a129bff5:important_5 |
| c32 Install, run and build inference is partial and installation commands are not verified, so this asset gives no install or run instructions. | observed | supported | analysis_5d9c9ae9a129bff5:lim_2 |
| c33 The analyzer's teaching notes conflict with the packet: one says no bounded execution path exists although paths are present, and another names test_cli_vectors.py as the starting point. | inferred | supported | analysis_5d9c9ae9a129bff5:claim_4d30ade3e21e, analysis_5d9c9ae9a129bff5:claim_34d2322830c1, analysis_5d9c9ae9a129bff5:exec_11e5ff5e359f |
| c34 Files over 400 kB, minified bundles and vendored directories are inventoried but not parsed under the analyzer's bounds. | observed | supported | analysis_5d9c9ae9a129bff5:lim_6 |
| c35 Dynamic dispatch, reflection and runtime framework behavior are outside what static analysis can establish here. | inferred | supported | analysis_5d9c9ae9a129bff5:claim_7c9925f9c8f4, analysis_5d9c9ae9a129bff5:lim_1 |
| c36 Whether any entrypoint actually runs, and what output it produces, is not established by this analysis. | unresolved | supported | analysis_5d9c9ae9a129bff5:lim_2, analysis_5d9c9ae9a129bff5:claim_7c9925f9c8f4 |
Sources, rights and disclosure · attribution-license-templates/v0.1
Rights notice. Original repository hosted on GitHub. Repository source code, documentation, names, media, and related project materials remain subject to the rights of their respective authors, contributors, and other rights holders and to applicable repository license terms.
Platform notice. GitHub is the source hosting platform for the linked repository. GitHub and related marks are trademarks of GitHub, Inc. EVEMISS Technology is not affiliated with or endorsed by GitHub unless explicitly stated otherwise.
How this page is produced. This page was produced using revision-aware repository analysis and AI-assisted editorial tooling. Technical claims are tied to the analyzed repository revision and may be revalidated when the source repository changes.
AI-assisted analysis. Reviewed by EVEMISS Technology through human–AI collaborative review. · Report a rights concern · All repository guides