如何解决Windows10虚拟环境pip安装python-snappy的Failed building wheel错误

错误现象 #

在Windows10的wave-buoy虚拟环境执行pip install python-snappy时，出现编译失败，核心报错为：

src/snappy/snappymodule.cc(33): fatal error C1083: Cannot open include file: 'snappy-c.h': No such file or directory

完整报错输出：

(wave-buoy) C:\Users\ricar\Desktop\oceanum_apps>pip install python-snappy
Collecting python-snappy
  Using cached python-snappy-0.6.1.tar.gz (24 kB)
  Preparing metadata (setup.py) ... done
Building wheels for collected packages: python-snappy
  Building wheel for python-snappy (setup.py) ... error
  error: subprocess-exited-with-error
  
  × python setup.py bdist_wheel did not run successfully.
  │ exit code: 1
  ╰─> [27 lines of output]
      C:\Users\ricar\Desktop\oceanum_apps\wave-buoy\Lib\site-packages\setuptools\_distutils\dist.py:265: UserWarning: Unknown distribution option: 'cffi_modules'
        warnings.warn(msg)
      running bdist_wheel
      running build
      running build_py
      creating build
      creating build\lib.win-amd64-cpython-311
      creating build\lib.win-amd64-cpython-311\snappy
      copying src\snappy\hadoop_snappy.py -> build\lib.win-amd64-cpython-311\snappy
      copying src\snappy\snappy.py -> build\lib.win-amd64-cpython-311\snappy
      copying src\snappy\snappy_cffi.py -> build\lib.win-amd64-cpython-311\snappy
      copying src\snappy\snappy_cffi_builder.py -> build\lib.win-amd64-cpython-311\snappy
      copying src\snappy\snappy_formats.py -> build\lib.win-amd64-cpython-311\snappy
      copying src\snappy\__init__.py -> build\lib.win-amd64-cpython-311\snappy
      copying src\snappy\__main__.py -> build\lib.win-amd64-cpython-311\snappy
      running build_ext
      building 'snappy._snappy' extension
      creating build\temp.win-amd64-cpython-311
      creating build\temp.win-amd64-cpython-311\Release
      creating build\temp.win-amd64-cpython-311\Release\src
      creating build\temp.win-amd64-cpython-311\Release\src\snappy
      "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Tools\MSVC\14.29.30133\bin\HostX86\x64\cl.exe" /c /nologo /O2 /W3 /GL /DNDEBUG /MD -IC:\Users\ricar\Desktop\oceanum_apps\wave-buoy\include -IC:\Users\ricar\AppData\Local\Programs\Python\Python311\include -IC:\Users\ricar\AppData\Local\Programs\Python\Python311\Include "-IC:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Tools\MSVC\14.29.30133\include" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\ucrt" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\shared" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\um" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\winrt" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\cppwinrt" /Tcsrc/snappy/crc32c.c /Fobuild\temp.win-amd64-cpython-311\Release\src/snappy/crc32c.obj
      crc32c.c
      "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Tools\MSVC\14.29.30133\bin\HostX86\x64\cl.exe" /c /nologo /O2 /W3 /GL /DNDEBUG /MD -IC:\Users\ricar\Desktop\oceanum_apps\wave-buoy\include -IC:\Users\ricar\AppData\Local\Programs\Python\Python311\include -IC:\Users\ricar\AppData\Local\Programs\Python\Python311\Include "-IC:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Tools\MSVC\14.29.30133\include" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\ucrt" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\shared" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\um" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\winrt" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\cppwinrt" /EHsc /Tpsrc/snappy/snappymodule.cc /Fobuild\temp.win-amd64-cpython-311\Release\src/snappy/snappymodule.obj
      snappymodule.cc
      src/snappy/snappymodule.cc(33): fatal error C1083: Cannot open include file: 'snappy-c.h': No such file or directory
      error: command 'C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\BuildTools\\VC\\Tools\\MSVC\\14.29.30133\\bin\\HostX86\\x64\\cl.exe' failed with exit code 2
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for python-snappy
  Running setup.py clean for python-snappy
Failed to build python-snappy
ERROR: Could not build wheels for python-snappy, which is required to install pyproject.toml-based projects

(wave-buoy) C:\Users\ricar\Desktop\oceanum_apps>

解决方法 #

方法1：安装预编译的wheel包（推荐） #

Windows下编译python-snappy需依赖snappy C库，直接用预编译wheel包可跳过编译步骤：

1. 确认你的Python版本（例如报错中的3.11，64位）
2. 获取对应版本的python_snappy wheel文件（格式为python_snappy-<版本号>-cp<Python版本>-cp<Python版本>-win_amd64.whl）
3. 在虚拟环境中执行安装命令：

pip install python_snappy-0.6.1-cp311-cp311-win_amd64.whl

方法2：手动配置snappy依赖后编译安装 #

若需编译安装，需先配置snappy C库：

1. 下载snappy的Windows预编译二进制包，解压得到include和lib目录
2. 将include目录下的snappy-c.h、snappy.h等头文件复制到虚拟环境的include目录（如C:\Users\ricar\Desktop\oceanum_apps\wave-buoy\include）
3. 将lib目录下的snappy.lib等库文件复制到虚拟环境的Lib目录或系统库目录
4. 重新执行pip install python-snappy

方法3：使用conda安装（适用于conda虚拟环境） #

如果你的虚拟环境由conda创建，可直接通过conda安装，它会自动处理依赖：

conda install python-snappy

内容的提问来源于stack exchange，提问作者Ricardo Motta Paes