安装 OCRmyPDF

安装 OCRmyPDF 最简单的方法是遵循您操作系统/平台的步骤。然而，此版本可能不是最新的。

这些平台提供一行命令安装

Debian, Ubuntu	`apt install ocrmypdf`
Windows Subsystem for Linux	`apt install ocrmypdf`
Fedora	`dnf install ocrmypdf tesseract-osd`
macOS (Homebrew)	`brew install ocrmypdf`
macOS (MacPorts)	`port install ocrmypdf`
LinuxBrew	`brew install ocrmypdf`
FreeBSD	`pkg install textproc/py-ocrmypdf`
Snap (snapcraft 打包)	`snap install ocrmypdf`

下面概述了更详细的步骤。如果您想手动安装，或者安装比您平台提供的版本更新的版本，请继续阅读。

在 Linux 上安装 

Debian 和 Ubuntu 20.04 或更新版本 

Debian 和 Ubuntu 中的 OCRmyPDF 版本

Debian 或 Ubuntu 用户可以简单地

apt install ocrmypdf

如上表所示，Debian 和 Ubuntu 的发布版本可能会落后于最新版本。如果您的平台可用的版本过时，您可以选择从源代码安装最新版本。参见从源代码安装 HEAD 版本。

要了解您的平台版本可用性的完整详情，请查看Debian Package Tracker 或 Ubuntu launchpad.net。

注意

目前，Debian 和 Ubuntu 的 OCRmyPDF 版本省略了 JBIG2 编码器。没有它，OCRmyPDF 也能正常工作，但会生成更大的输出文件。如果您从源代码构建 jbig2enc，ocrmypdf 将自动检测 PATH 上的它（特别是 jbig2 二进制文件）。要添加 JBIG2 编码，请参见安装 JBIG2 编码器。

Fedora 

OCRmyPDF 版本

Fedora 用户可以简单地

dnf install ocrmypdf tesseract-osd

要了解版本可用性的完整详情，请查看 Fedora Package Tracker。

如果您的平台可用的版本过时，您可以选择从源代码安装最新版本。参见从源代码安装 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 获取 traineddata 文件，并将它们放在 /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 最方便的方法是使用 Linux 上的 Homebrew (Linuxbrew)。

brew install ocrmypdf

Arch Linux (AUR)

Arch User Repository (AUR) 中有一个 OCRmyPDF 的包。

不允许以 root 用户身份安装 AUR 包，因此您必须首先设置一个非 root 用户并配置 sudo。标准的 Docker 镜像 archlinux/base:latest 没有配置非 root 用户，因此该镜像的用户必须遵循这些指南。如果您使用的是 VM 镜像，例如官方 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 formula。要在 macOS 上安装

brew install ocrmypdf

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

brew install tesseract-lang  # Optional: Install all language packs

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  # Option 2: for all language packs

更新 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 

如果尚未安装，请为 Windows Subsystem for Linux 安装 Ubuntu 22.04。
按照在 Ubuntu 22.04 上安装 OCRmyPDF 的步骤进行。
打开 Windows 命令提示符并创建符号链接

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

然后确认已安装 PyPI 中的预期版本 ( OCRmyPDF latest released version on PyPI )。

wsl ocrmypdf --version

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

Cygwin64 

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

python310 (or later)
python3?-devel
python3?-pip
python3?-lxml
python3?-imaging

   (where 3? means match the version of python3 you installed)

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

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

Docker 

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

在 FreeBSD 上安装 

pkg install textproc/py-ocrmypdf

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

安装 Docker 镜像 

对于一些用户来说，安装 Docker 镜像将比安装 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 补全 

项目的 misc/completion 文件夹中提供了 bash 和 fish 的补全脚本。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 位二进制 wheel。这包括 OCRmyPDF 依赖的许多库，例如 Pillow。向最终用户表达这一点的最简单方法是说我们不支持 32 位 Linux。

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