从源代码构建

外部库

注意

你**不需要安装所有支持的外部库**就可以使用 Pillow 的基本功能。**Zlib** 和 **libjpeg** 是默认情况下需要的。

注意

我们在 Docker images repo 中提供了一些 Dockerfile，用于安装一些操作系统的依赖项。

Pillow 的许多功能需要外部库

• **libjpeg** 提供 JPEG 功能。

  • Pillow 已在 libjpeg 版本 **6b**、**8**、**9-9d** 和 libjpeg-turbo 版本 **8** 上进行了测试。

  • 从 Pillow 3.0.0 开始，libjpeg 默认情况下是需要的。可以使用 -C jpeg=disable 标志禁用它。

• **zlib** 提供对压缩 PNG 的访问。

  • 从 Pillow 3.0.0 开始，zlib 默认情况下是需要的。可以使用 -C zlib=disable 标志禁用它。

• **libtiff** 提供压缩 TIFF 功能。

  • Pillow 已在 libtiff 版本 **3.x** 和 **4.0-4.6.0** 上进行了测试。

• **libfreetype** 提供与类型相关的服务。

• **littlecms** 提供颜色管理。

  • Pillow 2.2.1 及更低版本使用 liblcms1，Pillow 2.3.0 及更高版本使用 liblcms2。已在 **1.19** 和 **2.7-2.16** 上进行了测试。

• **libwebp** 提供 WebP 格式。

• **openjpeg** 提供 JPEG 2000 功能。

  • Pillow 已在 openjpeg **2.0.0**、**2.1.0**、**2.3.1**、**2.4.0**、**2.5.0** 和 **2.5.2** 上进行了测试。

  • Pillow **不支持**与 Debian Jessie 一起提供的早期 **1.5** 系列。

• **libimagequant** 提供改进的颜色量化。

  • Pillow 已在 libimagequant **2.6-4.3.3** 上进行了测试。

  • Libimagequant 采用 GPLv3 许可，比 Pillow 许可更严格，因此我们将不会分发包含 libimagequant 支持的二进制文件。

• **libraqm** 提供复杂的文本布局支持。

  • libraqm 提供双向文本支持（使用 FriBiDi）、造型（使用 HarfBuzz）和适当的脚本项目化。因此，Raqm 可以支持 Unicode 中涵盖的大多数书写系统。

  • libraqm 依赖于以下库：FreeType、HarfBuzz、FriBiDi，请确保在安装 libraqm 之前安装它们，如果你的系统中没有作为包提供。

  • 如果没有 libraqm，则不支持设置文本方向或字体功能。

  • 从 8.2.0 版本开始的 Pillow 轮子包含一个修改过的 libraqm 版本，该版本如果安装了 libfribidi，则会在运行时加载它。在 Windows 上，这需要编译 FriBiDi 并将 fribidi.dll 安装到 Dynamic-link library search order (Microsoft Learn) (fribidi-0.dll 或 libfribidi-0.dll 也被检测到) 中列出的目录中。请参阅 构建选项，了解如何构建此版本。

  • Pillow 的先前版本 (5.0.0 到 8.1.2) 在运行时动态链接 libraqm。

• **libxcb** 提供 X11 屏幕截图支持。

Linux

如果你没有从源代码构建 Python，请确保你已安装 Python 的开发库。

在 Debian 或 Ubuntu 中

sudo apt-get install python3-dev python3-setuptools

在 Fedora 中，命令是

sudo dnf install python3-devel redhat-rpm-config

在 Alpine 中，命令是

sudo apk add python3-dev py3-setuptools

注意

redhat-rpm-config 在 Fedora 23 上是必需的，但在更早的版本上不是必需的。

**Ubuntu 16.04 LTS - 22.04 LTS** 的先决条件使用以下命令安装

sudo apt-get install libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \
    libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk \
    libharfbuzz-dev libfribidi-dev libxcb1-dev

要安装 libraqm，请运行 sudo apt-get install meson，然后参阅 depends/install_raqm.sh。

在最近的 **Red Hat**、**CentOS** 或 **Fedora** 上安装先决条件

sudo dnf install libtiff-devel libjpeg-devel openjpeg2-devel zlib-devel \
    freetype-devel lcms2-devel libwebp-devel tcl-devel tk-devel \
    harfbuzz-devel fribidi-devel libraqm-devel libimagequant-devel libxcb-devel

请注意，包管理器可能是 yum 或 DNF，具体取决于确切的发行版。

在 **Alpine** 上安装先决条件

sudo apk add tiff-dev jpeg-dev openjpeg-dev zlib-dev freetype-dev lcms2-dev \
    libwebp-dev tcl-dev tk-dev harfbuzz-dev fribidi-dev libimagequant-dev \
    libxcb-dev libpng-dev

另请参阅 Test Infrastructure repo (https://github.com/python-pillow/docker-images) 中的 Dockerfile，了解其他经过测试的发行版的已知工作安装过程。

macOS

编译 Pillow 的部分内容需要 Xcode 命令行工具。这些工具可以通过在命令行中运行 xcode-select --install 来安装。即使你已安装了完整的 Xcode 包，也需要命令行工具。可能需要运行 sudo xcodebuild -license 来接受许可，然后才能使用这些工具。

安装外部库的最简单方法是通过 Homebrew。安装 Homebrew 后，运行

brew install libjpeg libtiff little-cms2 openjpeg webp

要在 macOS 上安装 libraqm，请使用 Homebrew 安装其依赖项

brew install freetype harfbuzz fribidi

然后参阅 depends/install_raqm_cmake.sh 来安装 libraqm。

Windows

我们建议你使用 PyPI 中的预构建轮子。如果你希望手动编译 Pillow，可以使用 winbuild 目录中的构建脚本，这些脚本用于 CI 测试和开发。这些脚本需要 Visual Studio 2017 或更高版本以及 NASM。

这些脚本还会从本地源代码副本安装 Pillow，因此之后不需要进行 安装 操作。

使用 MSYS2/MinGW 的 Windows

要使用 MSYS2 构建 Pillow，请确保你运行的是 **MSYS2 MinGW 32 位** 或 **MSYS2 MinGW 64 位** 控制台，而不是 **MSYS2** 本身。

以下说明针对 64 位构建，对于 32 位构建，请将所有 mingw-w64-x86_64- 替换为 mingw-w64-i686-。

确保你已安装 Python 和 GCC。

pacman -S \
    mingw-w64-x86_64-gcc \
    mingw-w64-x86_64-python3 \
    mingw-w64-x86_64-python3-pip \
    mingw-w64-x86_64-python3-setuptools

在 **MSYS2 MinGW 64 位** 上安装先决条件

pacman -S \
    mingw-w64-x86_64-libjpeg-turbo \
    mingw-w64-x86_64-zlib \
    mingw-w64-x86_64-libtiff \
    mingw-w64-x86_64-freetype \
    mingw-w64-x86_64-lcms2 \
    mingw-w64-x86_64-libwebp \
    mingw-w64-x86_64-openjpeg2 \
    mingw-w64-x86_64-libimagequant \
    mingw-w64-x86_64-libraqm

https://www.msys2.org/docs/python/ 指出 setuptools >= 60 不适用于 MSYS2。要解决此问题，在安装 Pillow 之前，你必须运行

export SETUPTOOLS_USE_DISTUTILS=stdlib

FreeBSD

注意

仅测试了 FreeBSD 10 和 11

确保你已安装 Python 的开发库。

sudo pkg install python3

在 **FreeBSD 10 或 11** 上安装先决条件

sudo pkg install jpeg-turbo tiff webp lcms2 freetype2 openjpeg harfbuzz fribidi libxcb

然后参阅 depends/install_raqm_cmake.sh 来安装 libraqm。

Android

已为在 Termux 环境中进行编译添加了基本的 Android 支持。可以通过以下命令安装依赖项

pkg install -y python ndk-sysroot clang make \
    libjpeg-turbo

这已在 ChromeOS 上的 Termux 应用程序中进行了测试，在 x86 上。

安装

安装完先决条件后，要从 PyPI 上的源代码安装 Pillow，请运行

python3 -m pip install --upgrade pip
python3 -m pip install --upgrade Pillow --no-binary :all:

如果先决条件安装在您机器的标准库位置（例如 /usr 或 /usr/local），则不需要额外的配置。如果它们安装在非标准位置，您可能需要通过编辑 setup.py 或 pyproject.toml 或在命令行添加环境变量来配置 setuptools 以使用这些位置。

CFLAGS="-I/usr/pkg/include" python3 -m pip install --upgrade Pillow --no-binary :all:

如果 Pillow 以前在没有必需先决条件的情况下构建，则可能需要手动清除 pip 缓存或使用 --no-cache-dir 选项在没有缓存的情况下构建，以强制使用新安装的外部库构建。

如果您想从本地源代码副本安装，可以使用 git clone https://github.com/python-pillow/Pillow 从 GitHub 克隆，或从 PyPI 下载并解压缩 压缩存档。

导航到 Pillow 目录后，运行

python3 -m pip install --upgrade pip
python3 -m pip install .

构建选项

• 配置设置：-C parallel=n。也可以使用环境变量给出：MAX_CONCURRENCY=n。Pillow 可以使用多处理来构建扩展。设置 -C parallel=n 将要使用的 CPU 数量设置为 n，或者可以使用设置 1 来禁用并行构建。默认情况下，它使用 4 个 CPU，或者如果 4 个 CPU 不可用，则使用尽可能多的 CPU。

• 配置设置：-C zlib=disable，-C jpeg=disable，-C tiff=disable，-C freetype=disable，-C raqm=disable，-C lcms=disable，-C webp=disable，-C jpeg2000=disable，-C imagequant=disable，-C xcb=disable。即使构建机器上存在开发库，也禁用构建相应的特性。

• 配置设置：-C zlib=enable，-C jpeg=enable，-C tiff=enable，-C freetype=enable，-C raqm=enable，-C lcms=enable，-C webp=enable，-C jpeg2000=enable，-C imagequant=enable，-C xcb=enable。要求构建相应的特性。如果找不到库，构建将引发异常。Tcl 和 Tk 必须一起使用。

• 配置设置：-C raqm=vendor，-C fribidi=vendor。这些标志用于编译 libraqm 的修改版本和在运行时动态加载 libfribidi 的 shim。这些用于编译标准 Pillow 轮子。编译 libraqm 需要一个符合 C99 的编译器。

• 配置设置：-C platform-guessing=disable。跳过所有平台相关的 include 和库目录的猜测，这些目录用于在环境变量中配置正确路径的自动化构建系统（例如 Buildroot）。

• 配置设置：-C debug=true。在 include 和库搜索过程中添加一个调试标志，以将所有搜索和找到的路径转储到 stdout。

示例用法

python3 -m pip install --upgrade Pillow -C [feature]=enable

旧版本

您可以从 PyPI 的 发布历史记录 和通过直接 URL 访问（例如 https://pypi.ac.cn/project/pillow/1.0/）下载旧发行版。