README

MarkItDown


!PyPI - Downloads

 [!IMPORTANT]
 MarkItDown performs I/O with the privileges of the current process. Like open() or requests.get(), it will access resources that the process itself can access. Sanitize your inputs in untrusted environments, and call the narrowest convert_ function needed for your use case (e.g., convert_stream(), or convert_local()). See the Security Considerations section of the documentation for more information.

MarkItDown is a lightweight Python utility for converting various files to Markdown for use with LLMs and related text analysis pipelines. To this end, it is most comparable to textract, but with a focus on preserving important document structure and content as Markdown (including: headings, lists, tables, links, etc.) While the output is often reasonably presentable and human-friendly, it is meant to be consumed by text analysis tools -- and may not be the best option for high-fidelity document conversions for human consumption.

MarkItDown currently supports the conversion from:

- PDF
- PowerPoint
- Word
- Excel
- Images (EXIF metadata and captioning)
- Audio (EXIF metadata and speech transcription)
- HTML
- Text-based formats (CSV, JSON, XML)
- ZIP files (iterates over contents)
- YouTube URLs
- EPubs
- ... and more!

NOTE: Image captioning and speech transcription rely on web-hosted services.

 Why Markdown?

Markdown is extremely close to plain text, with minimal markup or formatting, but still
provides a way to represent important document structure. Mainstream LLMs, such as
OpenAI's GPT-4o, natively "_speak_" Markdown, and often incorporate Markdown into their
responses unprompted. This suggests that they have been trained on vast amounts of
Markdown-formatted text, and understand it well. As a side benefit, Markdown conventions
are also highly token-efficient.

 Prerequisites
MarkItDown requires Python 3.10 through 3.14. It is recommended to use a virtual environment to avoid dependency conflicts.

With the standard Python installation, you can create and activate a virtual environment using the following commands:

bash
python -m venv .venv
source .venv/bin/activate


If using uv, you can create a virtual environment with:

bash
uv venv --python=3.12 .venv
source .venv/bin/activate
 NOTE: Be sure to use 'uv pip install' rather than just 'pip install' to install packages in this virtual environment


If you are using Anaconda, you can create a virtual environment with:

bash
conda create -n markitdown python=3.12
conda activate markitdown


 Installation

To install MarkItDown, use pip: pip install 'markitdown[all]'. Alternatively, you can install it from the source:

bash
git clone [email protected]:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'


 Usage

 Command-Line

bash
markitdown path-to-file.pdf  document.md


Or use -o to specify the output file:

bash
markitdown path-to-file.pdf -o document.md


You can also pipe content:

bash
cat path-to-file.pdf | mark

Top issues

Discussions

Latest release

What's Changed
 increase chunk size from 512 bytes to 64 KB for HTTP response reading by @YasirAlibrahem in https://github.com/microsoft/markitdown/pull/1511
 fix(wikipedia): accept mobile (m.wikipedia.org) URLs by @GopalGB in https://github.com/microsoft/markitdown/pull/1850
 fix: handle None sys.stdout.encoding in CLI output by @octo-patch in https://github.com/microsoft/markitdown/pull/1656
 Add language parameter for the audio transcription by @hchmch in https://github.com/microsoft/markitdown/pull/1295
 Perf: Optimize non-seekable stream buffering using shutil.copyfileobj by @YasirAl