安装OCRmyPDF

OCRmyPDF 在 PyPI 上的最新发布版本

安装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 版本

OCRmyPDF 在 PyPI 上的最新发布版本

Debian 或 Ubuntu 的用户可以简单地

apt install ocrmypdf

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

有关您平台上版本可用性的完整详细信息，请查看 Debian 包跟踪器或 Ubuntu launchpad.net。

注意

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

Fedora 

OCRmyPDF 版本

OCRmyPDF 在 PyPI 上的最新发布版本

Fedora 的用户可以简单地

dnf install ocrmypdf tesseract-osd

有关版本可用性的完整详细信息，请查看Fedora 包跟踪器。

如果您的平台上的版本已过时，您可以选择从源代码安装最新版本。请参阅从源代码安装HEAD版本。

注意

由于专利问题，Fedora 上的 OCRmyPDF 目前省略了 JBIG2 编码器。OCRmyPDF 在没有它的情况下也能正常工作，但会生成较大的输出文件。如果您从源代码构建 jbig2enc，ocrmypdf 7.0.0 及更高版本将自动在 PATH 上检测到它。要添加 JBIG2 编码，请参阅 Installing the JBIG2 encoder。

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 最方便的方法是使用 Linux 上的 Homebrew（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  # 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

OCRmyPDF 将检查 Windows 注册表和 Program Files 中的标准位置，以查找其所需的第三方软件（特别是 Tesseract 和 Ghostscript）。要覆盖 OCRmyPDF 选择的版本，您可以修改 PATH 环境变量。按照这些指示来更改 PATH。

警告

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

警告

不支持32位Windows。

适用于Linux的Windows子系统 

如果尚未安装，请为Windows子系统安装Ubuntu 22.04。
按照以下步骤在Ubuntu 22.04上安装OCRmyPDF。
打开Windows命令提示符并创建一个符号链接：

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

然后确认从PyPI安装的预期版本（ OCRmyPDF最新发布版本在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的所有依赖项更容易。

查看 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位二进制轮子。这包括OCRmyPDF依赖的许多库，例如Pillow。向最终用户表达这一点最简单的方式是说我们不支持32位Linux。

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