markpdfdown

环境要求

• Python 环境（pip 可用于安装依赖）
• uv 包管理器（README 推荐方式，可选）
• Docker（仅在容器方式下需要）
• Node.js / npx（仅在启动桌面应用时需要）
• OpenAI 或 OpenRouter 的大模型 API Key

安装与启动步骤

1. 1获取项目源码

   从 GitHub 克隆 markpdfdown 仓库，后续安装与配置命令都在该目录内执行。

   git clone https://github.com/MarkPDFdown/markpdfdown.git

   复制

2. 2安装 uv 工具

   README 推荐使用 uv 管理依赖；若已安装可跳过此步。

   curl -LsSf https://astral.sh/uv/install.sh | sh

   复制

3. 3安装项目依赖

   用 uv 同步依赖创建虚拟环境，再以开发模式安装本包；不用 uv 时可用 pip 命令。

   uv sync
   uv pip install -e .

   复制

4. 4配置环境变量

   先复制示例配置，再编辑 .env 填入模型名和 API Key 等信息。

   cp .env.sample .env

   复制

5. 5Docker 方式转换

   无需本地 Python 环境，通过标准输入传入 PDF，结果重定向写入 Markdown 文件。

   docker run -i -e MODEL_NAME=gpt-4o -e OPENAI_API_KEY=sk-xxxxxxxx markpdfdown < input.pdf > output.md

   复制

6. 6启动桌面应用

   想要图形界面时，用 npx 直接运行官方桌面应用，无需手动安装依赖。

   npx -y markpdfdown

   复制

关键配置

如何确认成功

执行转换命令后，输出文件（如 output.md）中生成结构化的 Markdown 内容，即表示运行成功。

常见问题

注意事项

• 转换过程会调用大模型 API，按量计费，处理大量 PDF 前请留意成本。
• .env 中含有 API Key，请勿提交到 Git 仓库或公开分享。
• .env.sample 中的配置项是最小示例，实际可用模型取决于你所选服务商。
• .env.sample 中的配置项是最小示例，实际可用模型取决于你所选服务商。