如何从源码安装 OCRmyPDF main 分支以使用尚未发布的最新版本
项目地址: https://gitcode.com/GitHub_Trending/oc/OCRmyPDF OCRmyPDF 为扫描版 PDF 添加可搜索的 OCR 文本层。用 apt、dnf 等发行版软件源安装时，docs/installation.md 提醒各发行版的版本可能落后于最新版（"Debian and Ubuntu releases may lag behind the latest version"）。当需要使用 main 分支上、尚未随发行版发布的更新时，文档的 "Installing HEAD revision from sources" 一节给出了完整的源码安装路径。下面按该节整理操作：前提是有 git 和 Python 3.11 或更新版本（文档推荐 3.12+），目标是得到一个可运行 ocrmypdf 的 main 分支环境。
准备条件：git、Python 与外部程序
文档把依赖分为两类，安装方式完全不同：
- Python 依赖（fpdf2、pikepdf、pypdfium2、uharfbuzz 等，声明在 pyproject.toml）由安装器自动解析安装；
- 外部程序必须用操作系统包管理器安装，文档明确说明 "must be satisfied using the operating system package manager.
pipcannot provide them"。
外部程序要求（来自 "Requirements for pip and HEAD install" 一节）：
- Python 3.11 或更新（3.12+ 推荐）
- Tesseract 4.1.1 或更新
- Ghostscript 9.54+ 或 pypdfium2（Python 包）之一，用于 PDF 栅格化
- Ghostscript 9.54+ 或 verapdf 之一，用于 PDF/A 输出
- fonts-noto 或等效字体包（系统包，推荐）
- jbig2enc 0.29 或更新（可选）、pngquant 2.5 或更新（可选）、unpaper 6.1（可选）
自 17.0.0 起 Ghostscript 变为可选：pypdfium2 可用于 PDF 栅格化，verapdf 可验证投机性 PDF/A 转换。文档同时给出经验建议：最好同时安装 Ghostscript 和 pypdfium2，前者对某些 PDF/A 转换是必需的，后者栅格化更快。
按系统准备依赖
以 RHEL 9 为例，文档给出的系统依赖准备命令：
dnf install python3.12 python3.12-pip
dnf install ghostscript tesseract
Debian/Ubuntu 用户，文档的建议是先安装平台版本以满足系统依赖，再用源码安装：
sudo apt-get update
sudo apt-get -y install ocrmypdf
其他发行版按上面同一份要求列表，用各自的包管理器安装 Tesseract、Ghostscript 等；verapdf 同样通过发行版包管理器安装。
字体（推荐项）：
apt install fonts-noto # Debian/Ubuntu
dnf install google-noto-fonts-all # Fedora
OCRmyPDF 只内置一种拉丁字体，其余从系统已安装字体中发现；如果系统字体缺某字符的字形，OCRmyPDF 会给出警告（文本层依然可搜索，只影响高亮显示效果）。
注意文档的版本边界：推荐使用全部软件的 64 位版本，"We don't support any 32-bit system, including 32-bit Python or 32-bit Ghostscript on Windows"。
主路径：克隆 main 分支并执行 uv sync
文档推荐用 uv 从源码安装：
git clone -b main https://gitcode.com/GitHub_Trending/oc/OCRmyPDF
cd OCRmyPDF
pip install uv # If not already installed
uv sync
uv sync 会在克隆目录内创建虚拟环境并安装全部 Python 依赖。然后激活环境：
source .venv/bin/activate
Windows 下激活命令为 .venv\Scripts\activate。
文档特别注明：ocrmypdf 只有在虚拟环境激活时才可用，每次使用前先执行上面的 activate 命令。
验证安装是否成功
按文档给出的检查方式，激活环境后运行：
ocrmypdf --help
文档把这条命令作为"命令行程序已可用"的确认（"The command line program should now be available"）。再确认实际装入的版本：
ocrmypdf --version
文档在其他安装场景中即用 ocrmypdf --version 来确认安装结果。
安装或运行过程中如果发现依赖缺失，文档描述了两个提示点：
- 安装时：pip 安装器运行时会提示缺失的依赖（"When the
pipinstaller runs, it will alert you if dependencies are missing"）； - 运行时：脚本会通知你需要安装哪些依赖。docs/advanced.md 的返回码表定义退出码 3 =
missing_dependency，含义是 "An external program required by OCRmyPDF is missing"。遇到该退出码时，回到"准备条件"一节补齐对应的外部程序。
文档还提醒：OCRmyPDF 对依赖有具体版本要求，比 release notes 中提到的版本更旧的依赖很可能不兼容。
替代安装方式（可选）
不想用 uv 时，文档在 "Installing HEAD revision from sources" 一节给出两条替代路径。
直接用 pip 从版本库安装：
pip install git+https://gitcode.com/GitHub_Trending/oc/OCRmyPDF
或者以可编辑模式安装，文档说明其用途是 "install in editable mode allowing customization"，便于在源码树内做自定义：
git clone -b main https://gitcode.com/GitHub_Trending/oc/OCRmyPDF
cd OCRmyPDF
pip install -e .
如果希望所有组件都从源码构建，文档指出需要先从源码构建并安装 pikepdf（按其官方文档操作），确认 pikepdf 可用后再继续。
可选扩展：附加功能与开发依赖
安装完成后，同一仓库内还可用 uv 加装文档列出的用户功能（括号内为文档原注释）：
uv sync --extra watcher # File watching service
uv sync --extra webservice # Streamlit web UI
uv sync --extra watcher --extra webservice # Multiple features
如果目标是参与开发而不仅是使用，文档给出的全量开发依赖安装是：
uv sync --all-groups
JBIG2 编码属于可选功能：源码构建 jbig2enc 后，OCRmyPDF 会自动在 PATH 上发现它，安装方法见 docs/jbig2.md。
限制说明
- 源码安装的
ocrmypdf只存在于克隆目录的.venv中，退出环境后需重新激活才能使用； - 外部程序（Tesseract、Ghostscript 等）不随 pip/uv 安装，缺失时表现为安装器提示或运行期退出码 3；
- 不支持任何 32 位系统（包括 32 位 Python 或 Windows 上的 32 位 Ghostscript）；
- main 分支领先于发行版打包版本，依赖版本要求以 release notes 为准。
验证通过后，即可按 README.md 中的基本用法处理文件，例如 ocrmypdf input_scanned.pdf output_searchable.pdf（文件名替换为自己的文件），更多用法见 docs/cookbook.md。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
