安装Python包时持续出现wheel构建失败（zlib依赖缺失）

问题描述 #

安装Pillow、matplotlib等Python包时，出现zlib头文件/库文件缺失错误，导致无法构建wheel，具体错误日志如下：

请查看安装说明：
     https://pillow.readthedocs.io/en/latest/installation.html

  Traceback (most recent call last):
    File "C:\Users\johan\AppData\Local\Temp\pip-install-vl7cs7d8\pillow_b1e69e937cae422cb43abf0a9527a8e6\setup.py", line 852, in <module>
      setup(
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\__init__.py", line 108, in setup
      return distutils.core.setup(**attrs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\_distutils\core.py", line 185, in setup
      return run_commands(dist)
             ^^^^^^^^^^^^^^^^^^
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\_distutils\core.py", line 201, in run_commands
      dist.run_commands()
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\_distutils\dist.py", line 969, in run_commands
      self.run_command(cmd)
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\dist.py", line 1221, in run_command
      super().run_command(command)
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\_distutils\dist.py", line 988, in run_command
      cmd_obj.run()
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\wheel\bdist_wheel.py", line 325, in run
      self.run_command("build")
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\_distutils\cmd.py", line 318, in run_command
      self.distribution.run_command(command)
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\dist.py", line 1221, in run_command
      super().run_command(command)
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\_distutils\dist.py", line 988, in run_command
      cmd_obj.run()
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\_distutils\command\build.py", line 131, in run
      self.run_command(cmd_name)
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\_distutils\cmd.py", line 318, in run_command
      self.distribution.run_command(command)
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\dist.py", line 1221, in run_command
      super().run_command(command)
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\_distutils\dist.py", line 988, in run_command
      cmd_obj.run()
    File "C:\Users\johan\AppData\Local\Programs\Python\Python311\Lib\site-packages\setuptools\_distutils\command\build_ext.py", line 345, in run
      self.build_extensions()
    File "C:\Users\johan\AppData\Local\Temp\pip-install-vl7cs7d8\pillow_b1e69e937cae422cb43abf0a9527a8e6\setup.py", line 687, in build_extensions
      raise RequiredDependencyException(f)
  RequiredDependencyException: zlib

  During handling of the above exception, another exception occurred:

  Traceback (most recent call last):
    File "<string>", line 2, in <module>
    File "<pip-setuptools-caller>", line 34, in <module>
    File "C:\Users\johan\AppData\Local\Temp\pip-install-vl7cs7d8\pillow_b1e69e937cae422cb43abf0a9527a8e6\setup.py", line 903, in <module>
      raise RequiredDependencyException(msg)
  RequiredDependencyException:

  无法找到zlib的头文件或库文件，
  zlib是从源码编译Pillow所需的依赖项。

  请查看安装说明：
     https://pillow.readthedocs.io/en/latest/installation.html


  [end of output]
注意：此错误源自子进程，大概率并非pip的问题。
ERROR: Failed building wheel for Pillow
Running setup.py clean for Pillow
Failed to build Pillow
ERROR: Could not build wheels for Pillow, which is required to install pyproject.toml-based projects

解决方案 #

1. 强制使用预编译二进制包（最简单有效） #

直接让pip跳过源码编译，使用官方预编译的wheel包，执行命令：

pip install --only-binary :all: pillow matplotlib

2. 安装Windows编译工具链（若必须源码编译） #

如果需要从源码编译包，安装Visual Studio的C++构建工具：

• 打开Visual Studio Installer，选择「Desktop development with C++」工作负载
• 确保勾选「Windows SDK」和「C++ build tools」组件，完成安装后重启命令行，再尝试安装包。

3. 手动配置zlib依赖（进阶） #

• 下载zlib的预编译库文件
• 设置环境变量指向zlib的头文件和库文件目录：

  set ZLIB_INCLUDE_DIR=C:\path\to\zlib\include
  set ZLIB_LIBRARY=C:\path\to\zlib\lib\zlib.lib
  

• 然后执行pip install pillow matplotlib

内容的提问来源于stack exchange，提问作者Johanvm