markitdown

环境要求

• Python 3.12（README 示例使用 python=3.12 创建环境）
• pip（用于安装 markitdown 包）
• 可选：Docker（使用容器方式构建/运行镜像）
• 可选：hatch（运行测试时需要）

安装与启动步骤

1. 1用 pip 安装

   直接通过 pip 安装 MarkItDown，方括号中的 all 表示安装全部可选依赖（PDF、OCR、音频等）。

   pip install 'markitdown[all]'

   复制

2. 2创建虚拟环境

   可选。README 提示在虚拟环境中应使用 uv pip install 而非 pip install；Anaconda 用户可按下方命令建环境。

   conda create -n markitdown python=3.12
   conda activate markitdown

   复制

3. 3从源码安装

   可选。克隆官方仓库后在本地以可编辑模式安装 markitdown 包，注意路径是 packages/markitdown。

   git clone git@github.com:microsoft/markitdown.git
   cd markitdown
   pip install -e 'packages/markitdown[all]'

   复制

4. 4构建 Docker 镜像

   可选。在仓库根目录（含 Dockerfile 的位置）构建名为 markitdown:latest 的镜像。

   docker build -t markitdown:latest .

   复制

5. 5转换文件为 Markdown

   用 Docker 镜像把本地 PDF 转成 Markdown：输入重定向进容器，输出重定向写入 output.md。把 ~/your-file.pdf 换成你自己的文件路径。

   docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

   复制

6. 6运行测试与检查

   可选。进入 markitdown 包目录，安装 hatch 后进入其 shell 执行测试；提交 PR 前可运行 pre-commit 检查。

   cd packages/markitdown
   pip install hatch
   hatch shell
   hatch test
   pre-commit run --all-files

   复制

如何确认成功

执行转换命令后，当前目录下的 output.md 中能看到原文档转换出的 Markdown 内容（标题、列表、表格等），即表示安装与运行成功。

常见问题

注意事项

• MarkItDown 以当前进程的权限执行 I/O，会访问该进程本身可访问的资源；在不可信环境中务必清理输入，并调用最小范围的 convert_* 函数（如 convert_stream()、convert_local()）。
• 在虚拟环境中安装时，README 强调使用 uv pip install 而不是 pip install。
• README 未给出 Python API 的完整调用样例和 CLI 参数，实际编码请以官方文档与仓库说明为准。