安装

安装 OCRmyPDF 最简单的方法是按照你的操作系统或平台的步骤来操作。不过，这个版本可能会过时。

以下平台支持一键安装：

下面会详细介绍更详细的步骤。如果你想手动安装，或者安装比你的平台提供的最新版本，请继续阅读。

平台特定步骤

• 在 Linux 上安装

◦   [Debian 和 Ubuntu 20.04 或更新版本](#debian-and-ubuntu-20-04-or-newer)
◦   [Fedora](#fedora)
◦   [RHEL 9](#rhel-9)
◦   [在 Ubuntu 22.04 LTS 上安装最新版本](#installing-the-latest-version-on-ubuntu-22-04-lts)
◦   [Ubuntu 20.04 LTS](#ubuntu-20-04-lts)
◦   [Arch Linux (AUR)](#arch-linux-aur)
◦   [Alpine Linux](#alpine-linux)
◦   [Gentoo Linux](#gentoo-linux)
◦   [其他 Linux 包](#other-linux-packages)

• 在 macOS 上安装

◦   [Homebrew](#homebrew)
◦   [MacPorts](#macports)
◦   [在 macOS 上手动安装](#manual-installation-on-macos)

• 在 Windows 上安装

◦   [原生 Windows](#native-windows)
◦   [Windows Subsystem for Linux](#windows-subsystem-for-linux)
◦   [Cygwin64](#cygwin64)
◦   [Docker](#docker)

• 在 FreeBSD 上安装

• 安装 Docker 镜像

• 使用 Python pip 安装

• 使用 pipx 安装

◦   [pip 和 HEAD 安装的要求](#requirements-for-pip-and-head-install)

• 从源码安装 HEAD 版本

◦   [用于开发](#for-development)

• Shell 自动补全

• 关于 32 位支持的说明

在 Linux 上安装

Debian 和 Ubuntu 20.04 或更新版本

Debian 或 Ubuntu 用户可以简单地执行：

apt install ocrmypdf

如上表所示，Debian 和 Ubuntu 的版本可能会落后于最新版本。如果你的平台提供的版本过时了，你可以选择从源码安装最新版本。详见 从源码安装 HEAD 版本。

要查看你的平台的具体版本信息，请访问 Debian 包跟踪器 或 Ubuntu launchpad.net。

注意

Debian 和 Ubuntu 的 OCRmyPDF 目前不包含 JBIG2 编码器。OCRmyPDF 在没有它的情况下也能正常工作，但会生成更大的输出文件。如果你从源码构建了 jbig2enc，ocrmypdf 会自动检测到它（特别是 jbig2 二进制文件）并将其添加到 PATH 中。要添加 JBIG2 编码，请参阅 安装 JBIG2 编码器。

Fedora

Fedora 用户可以简单地执行：

dnf install ocrmypdf tesseract-osd

要查看你的平台的具体版本信息，请访问 Fedora 包跟踪器。

如果你的平台提供的版本过时了，你可以选择从源码安装最新版本。详见 从源码安装 HEAD 版本。

注意

由于专利问题，Fedora 的 OCRmyPDF 目前不包含 JBIG2 编码器。OCRmyPDF 在没有它的情况下也能正常工作，但会生成更大的输出文件。如果你从源码构建了 jbig2enc，ocrmypdf 7.0.0 及更高版本会自动检测到它并将其添加到 PATH 中。要添加 JBIG2 编码，请参阅 安装 JBIG2 编码器。

RHEL 9

首先安装 Python 3.11：

dnf install python3.11 python3.11-pip

然后，按照 pip 和 HEAD 安装的要求 安装依赖项：

dnf install ghostscript tesseract

并在虚拟环境中构建 ocrmypdf：

python3.11 -m venv .venv

要添加 JBIG2 编码，请参阅 安装 JBIG2 编码器。

注意 Fedora 的语言数据包尚未分支到 RHEL/EPEL，但你可以直接从 tesseract 获取训练数据文件，并将其放置在 /usr/share/tesseract/tessdata 中。

在 Ubuntu 22.04 LTS 上安装最新版本

Ubuntu 22.04 包含了 ocrmypdf 13.4.0，你可以通过 apt install ocrmypdf 安装。要为当前用户安装更新的版本，请按照以下步骤操作：

sudo apt-get update sudo apt-get -y install ocrmypdf python3-pip

pip install --user --upgrade ocrmypdf

如果你看到消息 WARNING: The script ocrmypdf is installed in '/home/$USER/.local/bin' which is not on PATH.，你可能需要重新登录或打开一个新的 shell，或者手动调整你的 PATH。

要添加 JBIG2 编码，请参阅 安装 JBIG2 编码器。

Ubuntu 20.04 LTS

Ubuntu 20.04 包含了 ocrmypdf 9.6.0，你可以通过 apt 安装。在较旧的 Ubuntu 上安装最新 OCRmyPDF 的最方便方法是使用 Homebrew on Linux (Linuxbrew)。

brew install ocrmypdf

Arch Linux (AUR)

Arch 用户仓库 (AUR) 中有一个 OCRmyPDF 包。

不允许以 root 用户安装 AUR 包，因此你必须先 设置一个非 root 用户 并 配置 sudo。标准的 Docker 镜像 archlinux/base:latest 没有配置非 root 用户，因此使用该镜像的用户必须按照这些指南操作。如果你使用的是虚拟机镜像，例如 官方 Vagrant 镜像，这些工作可能已经为你完成了。

接下来你应该安装 base-devel 包组。这包括构建包所需的标准工具，例如编译器和二进制工具。

sudo pacman -S --needed base-devel

现在你可以安装 OCRmyPDF 包了。

curl -O https://aur.archlinux.org/cgit/aur.git/snapshot/ocrmypdf.tar.gz tar xvzf ocrmypdf.tar.gz cd ocrmypdf makepkg -sri

此时你将拥有一个可用的 OCRmyPDF 安装，但 Tesseract 安装不会包含任何 OCR 语言数据。你可以安装 tesseract-data 包组 来添加所有支持的语言，或者使用该包列表来识别你所需语言的适当包。

sudo pacman -S tesseract-data-eng

作为此手动过程的替代方案，考虑使用 AUR 助手。这样的工具会自动获取、构建和安装 AUR 包，解决依赖关系（包括对 AUR 包的依赖），并简化升级过程。

如果在安装过程中遇到任何困难，请查看仓库包页面。

注意

OCRmyPDF AUR 包目前不包含 JBIG2 编码器。OCRmyPDF 在没有它的情况下也能正常工作，但会生成更大的输出文件。编码器可以从 jbig2enc-git AUR 包 中获取，并可以使用与安装 OCRmyPDF AUR 包相同的步骤进行安装。或者，可以按照 安装 JBIG2 编码器 中的说明从源码手动构建。如果安装了 JBIG2，OCRmyPDF 7.0.0 及更高版本会自动检测到它。

Alpine Linux

要在 Alpine Linux 上安装 OCRmyPDF，请执行：

apk add ocrmypdf

Gentoo Linux

要在 Gentoo Linux 上安装 OCRmyPDF，请使用以下命令：

eselect repository enable guru emaint sync --repo guru emerge --ask app-text/OCRmyPDF

其他 Linux 包

请参阅 Repology 页面。

一般来说，首先为你的系统安装 OCRmyPDF 包，然后可以选择使用 使用 Python pip 安装 的过程来安装更新的版本。

在 macOS 上安装

Homebrew

OCRmyPDF 现在是标准的 Homebrew 公式。要在 macOS 上安装，请执行：

brew install ocrmypdf

这将仅包含英语语言包。如果你需要其他语言，可以选择安装所有语言包：

brew install tesseract-lang # 可选：安装所有语言包

MacPorts

OCRmyPDF 包含在 MacPorts 中：

sudo port install ocrmypdf

请注意，虽然这会安装 tesseract，但你还需要安装适当的 tesseract 语言包。

在 macOS 上手动安装

这些说明可能适用于所有受 Homebrew 支持的 macOS 版本，用于安装比 Homebrew 提供的更当前的 OCRmyPDF 版本。请注意，Homebrew 版本通常与发布版本保持相当接近。

如果尚未安装，请先 安装 Homebrew。

更新 Homebrew：

brew update

安装或升级所需的 Homebrew 包（如果有缺失）。为此，使用 brew edit ocrmypdf 获取最新的 Homebrew 依赖项列表。你也可以检查 .workflows/build.yml。

这将包括英语、法语、德语和西班牙语语言包。如果你需要其他语言，可以选择安装所有语言包：

brew install tesseract-lang # 选项 2：安装所有语言包

更新 homebrew 的 pip：

pip install --upgrade pip

然后你可以为当前用户从 PyPI 安装 OCRmyPDF：

pip install --user ocrmypdf

现在命令行程序应该可用了：

ocrmypdf --help

在 Windows 上安装

原生 Windows

注意

某些步骤需要管理员权限。

你必须为 Windows 安装以下内容：

• Python 64 位

• Tesseract 64 位

• Ghostscript 64 位 使用 winget 包管理器：

• winget install -e --id Python.Python.3.11

• winget install -e --id UB-Mannheim.TesseractOCR

你需要手动安装 Ghostscript，因为它不再支持自动安装。

• Ghostscript 下载页面.`

（或者，使用 Chocolatey 包管理器，在管理员命令提示符下运行以下命令）：

• choco install python3

• choco install --pre tesseract

• choco install pngquant（可选）

上述任意一组命令都会安装所需的软件。目前没有单一命令可以安装所有 Windows 依赖项。

然后你可以使用 pip 安装 ocrmypdf。（这可以由用户或管理员执行）：

• python3 -m pip install ocrmypdf

如果你使用 WinGet 安装了 Python，则使用以下命令：

• py -m pip install ocrmypdf

并运行：

• py -m ocrmypdf

来启动 OCRmyPDF。

如果你打算在 Windows 机器上使用更多 Python 软件，考虑使用 pipx 或类似工具，为每个 Python 软件创建隔离的 Python 环境。

OCRmyPDF 会检查 Windows 注册表和 Program Files 中的标准路径，以找到它需要的第三方软件（特别是 Tesseract 和 Ghostscript）。要覆盖 OCRmyPDF 选择的版本，你可以修改 PATH 环境变量。按照这些说明 来更改 PATH。

警告

截至 2021 年初，用户报告了 Microsoft Store 版本的 Python 和 OCRmyPDF 的问题。这些问题影响了许多其他第三方 Python 包。请从 Python.org 或包管理器下载 Python，而不是使用 Microsoft Store 版本。

警告

不支持 32 位 Windows。

Windows Subsystem for Linux

1. 如果尚未安装，请安装适用于 Windows Subsystem for Linux 的 Ubuntu 22.04。

2. 按照 在 Ubuntu 22.04 上安装 OCRmyPDF 的步骤操作。

3. 打开 Windows 命令提示符并创建符号链接：

wsl sudo ln -s /home/$USER/.local/bin/ocrmypdf /usr/local/bin/ocrmypdf

然后确认安装的版本是 PyPI 上的最新版本 ()：

wsl ocrmypdf --version

然后你可以在 Windows 命令提示符或 Powershell 中运行 OCRmyPDF，前缀为 wsl，并从 Windows 程序或批处理文件中调用它。

Cygwin64

首先使用 setup-x86_64.exe 安装以下必备的 Cygwin 包：

python310（或更高版本） python3?-devel python3?-pip python3?-lxml python3?-imaging

（其中 3? 表示匹配你安装的 python3 版本）

gcc-g++ ghostscript libexempi3 libexempi-devel libffi6 libffi-devel pngquant qpdf libqpdf-devel tesseract-ocr tesseract-ocr-devel

然后打开 Cygwin 终端（即 mintty），运行以下命令。请注意，如果你使用的是 Cygwin Python 包附带的 pip 版本，命令名称为 pip3。如果你之后更新了 pip（例如使用 pip3 install --upgrade pip），则命令可能只是 pip 而不是 pip3：

pip3 install wheel pip3 install ocrmypdf

当前在 Cygwin 下不可用的可选依赖项是 “unpaper”。没有它，某些选项（如 --clean）会产生错误消息。然而，OCR 到文本层的功能仍然可用。

Docker

你也可以 在 Windows 上安装 Docker 容器。确保你的命令提示符可以运行 docker “hello world” 容器。

在 FreeBSD 上安装

pkg install textproc/py-ocrmypdf

要安装更新的版本，你可以尝试先使用 pkg 安装系统版本，然后使用 pip install --user ocrmypdf。

安装 Docker 镜像

对于某些用户来说，安装 Docker 镜像比安装 OCRmyPDF 的所有依赖项更容易。

有关更多信息，请参阅 OCRmyPDF Docker 镜像。

使用 Python pip 安装

OCRmyPDF 通过 PyPI 发布，因为这是安装最新版本的便捷方式。然而，PyPI 和 pip 无法解决 ocrmypdf 依赖于某些非 Python 系统库和程序的事实。

为了获得最佳效果，首先安装 你的平台版本 的 ocrmypdf，使用本文档中的其他说明。然后你可以使用 pip 获取最新版本（如果你的平台版本过时）。这很可能会满足大多数依赖项。

使用 ocrmypdf --version 确认安装的版本。

然后你可以从 Python wheels 安装最新的 OCRmyPDF。首先尝试：

pip install --user ocrmypdf

（如果出现消息 Requirement already satisfied: ocrmypdf in...，你需要使用 pip install --user --upgrade ocrmypdf。）

然后你应该能够运行 ocrmypdf --version 并看到最新版本。

使用 pipx 安装

一些用户可能更喜欢 pipx。与上述方法一样，你需要满足所有非 Python 依赖项。然后如果 pipx 已安装，你可以使用：

pipx run ocrmypdf

（如果未安装，pipx 会先安装。）

pip 和 HEAD 安装的要求

OCRmyPDF 目前需要安装以下外部程序和库，必须使用操作系统包管理器来满足。pip 无法提供它们。

需要以下版本：

• Python 3.10 或更高版本

• Ghostscript 9.54 或更高版本

• Tesseract 4.1.1 或更高版本

• jbig2enc 0.29 或更高版本

• pngquant 2.5 或更高版本

• unpaper 6.1

我们推荐所有软件的 64 位版本。（不支持 32 位版本，尽管在 Linux 上它们可能仍然有效。）

jbig2enc、pngquant 和 unpaper 是可选的。如果缺少某些功能将被禁用。OCRmyPDF 会在它们可用时自动检测到它们。

jbig2enc，如果存在，将用于优化单色图像的编码。这可以显著减小输出文件的大小。它不是必需的。jbig2enc 通常不适用于 Ubuntu 或 Debian，因为专利问题，但可以轻松地从源码构建。要添加 JBIG2 编码，请参阅 安装 JBIG2 编码器。

pngquant，如果存在，可选择性地用于优化 PDF 中 PNG 风格图像（实际上是任何无损编码的图像）的编码，通过有损量化到较小的调色板。它仅在 --optimize 参数为 2 或 3 时激活。

unpaper，如果存在，启用 --clean 和 --clean-final 命令行选项。

这些是除了 Python 包依赖项之外的，这意味着不幸的是，pip install 命令无法满足所有这些依赖项。

从源码安装 HEAD 版本

如果你已安装 git 和 Python 3.10 或更高版本，你可以从源码安装。当 pip 安装程序运行时，如果缺少依赖项，它会提醒你。

如果你更喜欢从源码构建所有内容，你需要 从源码构建 pikepdf。首先确保你可以构建并安装 pikepdf。

要在当前的 Python 3 环境中从源码安装 HEAD 版本：

pip install git+https://github.com/ocrmypdf/OCRmyPDF.git

或者，要安装为可编辑模式以允许自定义 OCRmyPDF，使用 -e 标志：

pip install -e git+https://github.com/ocrmypdf/OCRmyPDF.git

你可能会发现最容易在虚拟环境中安装，而不是系统范围内：

git clone -b main https://github.com/ocrmypdf/OCRmyPDF.git python3 -m venv .venv source .venv/bin/activate cd OCRmyPDF pip install .

然而，ocrmypdf 只会在你激活虚拟环境时在系统 PATH 中可用。

要运行程序：

ocrmypdf --help

如果尚未安装，脚本会通知你需要安装的依赖项。脚本需要特定版本的依赖项。比发布说明中提到的版本更旧的版本可能不兼容 OCRmyPDF。

用于开发

要安装所有开发和测试需求：

git clone -b main https://github.com/ocrmypdf/OCRmyPDF.git python -m venv .venv source .venv/bin/activate cd OCRmyPDF pip install -e .[test]

要添加 JBIG2 编码，请参阅 安装 JBIG2 编码器。

Shell 自动补全

bash 和 fish 的自动补全功能可在项目的 misc/completion 文件夹中找到。bash 补全可能兼容 zsh，但尚未确认。包维护者，请将这些文件安装到系统的适当位置。

要手动安装 bash 补全，将 misc/completion/ocrmypdf.bash 复制到 /etc/bash_completion.d/ocrmypdf（重命名文件）。

要手动安装 fish 补全，将 misc/completion/ocrmypdf.fish 复制到 ~/.config/fish/completions/ocrmypdf.fish。

关于 32 位支持的说明

许多 Python 库不再为 Linux 提供 32 位二进制 wheels。这包括 OCRmyPDF 依赖的许多库，例如 Pillow。向最终用户表达这一点最简单的方式是说我们不支持 32 位 Linux。

然而，如果你的 Linux 发行版仍然支持 32 位二进制文件，你仍然可以安装并使用 OCRmyPDF。会出现警告消息。实际上，OCRmyPDF 在处理大文档时可能需要超过 32 位内存空间，因此用户在使用它时会遇到实际限制。尽管如此，对于常见的 32 位 ARM NAS 或 Raspberry Pi 处理小文档的用例，它应该可以正常工作。