Python中PIL库怎么安装？推荐直接使用Pillow

当你在运行 Python 脚本或学习图像处理教程时，经常会看到 from PIL import Image 这样的导入语句。初学者按照直觉在终端中输入 pip install PIL，往往会遇到找不到对应版本或编译失败的报错。这是 Python 生态中一个非常经典的历史兼容性问题。本文将详细解答为什么推荐直接使用 Pillow、具体的安装与验证流程，以及背后的命名机制与常见排错技巧。

一、为什么不再安装 PIL，而是推荐 Pillow？

要理解这个问题的根源，需要了解 PIL 与 Pillow 的历史发展关系：

• 原始 PIL（Python Imaging Library）：诞生于 1995 年，曾是 Python 2 时代最核心的图像处理标配库。然而，该项目的官方更新在 2009 年发布的 1.1.7 版本后彻底停滞，并且从未正式支持过 Python 3。
• Pillow 的诞生：由于广泛的社区需求，开发者 Alex Clark 等人发起了名为 Pillow 的分支项目（Friendly Fork）。Pillow 完全继承了 PIL 的功能与 API，并加入了对 Python 3 的全方位适配、持续的安全修复、现代操作系统支持以及对更多图像格式（如 WebP、HEIF 等）的解码支持。

常见认知误区辨析：有些读者可能会疑惑：“既然代码里写的是 import PIL，那是不是必须存在一个叫 PIL 的安装包？”答案是否定的。在 PyPI（Python 官方包仓库）上，旧的 PIL 名称已经不可用于 Python 3。如果强行安装，包管理器会提示找不到满足要求的构建版本。如今整个 Python 社区公认的唯一标准就是安装 Pillow。

二、Pillow 的标准安装步骤与环境准备

安装 Pillow 非常简单，但在多 Python 版本或虚拟环境并存的机器上，建议遵循标准化操作流程，确保安装到预期的 Python 解释器中。

步骤 1：确认终端环境与 Python 版本

打开终端（Windows 下为 PowerShell 或 CMD，macOS / Linux 下为 Terminal），首先检查当前环境的 Python 及其配套的 pip：

# 查看当前 Python 版本（要求 Python 3.8 及以上）
python --version
# 或者在部分系统下使用 python3
python3 --version

# 查看 pip 版本及绑定的解释器路径
python -m pip --version

步骤 2：执行安装命令

推荐使用 python -m pip install 语法进行安装。与直接输入 pip install 相比，使用 python -m pip 可以 100% 确保第三方库安装到当前 python 命令指向的环境中，有效避免多版本路径冲突：

# 标准安装命令
python -m pip install Pillow

# 如果系统默认使用 python3 命令
python3 -m pip install Pillow

如果你使用的是 Anaconda 或 Miniconda 环境，可以使用 conda 命令进行安装：

conda install pillow

步骤 3：验证安装结果

安装完成后，无需编写完整的 Python 文件，可直接在终端中运行一行单行代码进行验证：

python -c "import PIL; print('Pillow 版本:', PIL.__version__)"

若终端输出类似 Pillow 版本: 10.3.0 的信息，即代表安装圆满成功。

三、关键机制：为什么安装叫 Pillow，导入却叫 PIL？

很多初学者在此处感到困惑：为什么不能直接 pip install PIL，或者为什么在代码中不写成 import Pillow？

这涉及 Python 的两个层级概念：分发包名（Distribution Package Name）与顶层模块名（Import Package / Module Name）。

• 分发包名（Pillow）：这是在 PyPI 上注册、供 pip 管理的名称。开发者在终端里执行 pip install Pillow 时，pip 从服务器下载名为 Pillow 的 wheel 压缩包或源码包。
• 模块名（PIL）：这是 Python 代码在运行时用来导入的命名空间。解压安装 Pillow 后，进入 Python 解释器的 site-packages 目录，你会发现其实际生成的文件夹名称就是 PIL/。

为什么这样设计？核心目的是保持最大程度的向后兼容性（Backward Compatibility）。在 Pillow 诞生之前，全球已有数以百万计的开源项目和企业系统写满了 from PIL import Image。如果 Pillow 把导入名改为 import Pillow，那么所有迁移到 Python 3 的项目都必须逐行重构旧代码。通过保持 PIL 这个模块名不变，旧项目升级只需改动一行 requirements.txt，业务代码完全不需要动任何一行，极大降低了迁移成本。

四、基础代码使用示例

安装完成后，你可以通过下面这段标准的入门示例测试基本图像创建与格式转换功能：

from PIL import Image, ImageDraw

# 1. 创建一张 300x200 像素、背景为暖灰色的新图片
img = Image.new("RGB", (300, 200), color="#F7F4ED")

# 2. 在图片上绘制一个简单的矩形图形
draw = ImageDraw.Draw(img)
draw.rectangle([50, 50, 250, 150], outline="#464B48", fill="#8A9478", width=2)

# 3. 保存为本地图片文件
img.save("example.png")
print("测试图片生成成功：example.png")

如果在执行过程中没有抛出任何错误，并且当前目录下生成了 example.png，就说明 Pillow 已经在你的环境中正常运作了。

五、常见问题排查与修复方案

在日常安装和使用过程中，开发者最容易遇到以下三类典型问题：

1. 依然提示 ModuleNotFoundError: No module named 'PIL'

原因排查：这通常是由于多环境不一致引起的。例如，终端里执行 pip install Pillow 时使用的是系统的 Python，而你运行代码或启动 IDE（如 VS Code、PyCharm）时选择的是虚拟环境（如 venv 或 conda）解释器，导致目标环境中实际上并未安装 Pillow。

解决方法：

• 如果使用虚拟环境，先激活对应环境（如 source venv/bin/activate 或 conda activate myenv），然后再执行安装。
• 在代码脚本开头加入以下调试语句打印当前执行环境路径：

  import sys
  print(sys.executable)

  然后在终端中直接使用该具体路径运行 pip，例如：/path/to/venv/bin/python -m pip install Pillow。

2. 曾误安装过旧版本 PIL 导致文件冲突

如果曾经尝试在旧环境里安装过非官方的 PIL 包或旧版编译残留，可能会导致安装 Pillow 后出现符号冲突或导入异常。

解决方法：先彻底卸载旧残留包，再纯净重装 Pillow：

python -m pip uninstall PIL Pillow -y
python -m pip install --upgrade Pillow

3. Linux / Docker 最小化系统中的底层依赖

在大多数 Windows 和 macOS 电脑上，pip 会直接下载官方打包好的预编译 Wheel 文件（包含底层依赖）。但在某些 Linux 发行版（如 Alpine Linux 或轻量 Docker 镜像）中，可能会 fallback 到从源码编译，此时若缺少底层 C 开发库（如 libjpeg、zlib）会报编译错误。

解决方法：在 Ubuntu/Debian 系统下提前安装编译依赖：

sudo apt-get update
sudo apt-get install -y libjpeg-dev zlib1g-dev python3-dev

对于大部分常规桌面用户，直接执行 pip install Pillow 即可自动获取预编译二进制，无需手动编译。

六、全文总结

总而言之，在 Python 的图像处理领域，遇到任何有关 PIL 的说明，直接将其对应为现代的 Pillow 即可。通过规范使用 python -m pip install Pillow，你可以在保留历史代码写法的同时，享受到现代开源社区带来的稳定性和高性能支持。