pip安装mysqlclient时出现failure to build wheels错误求助

问题核心 #

你使用Python 3.12 + MySQL 8.0环境，安装mysqlclient时触发failure to build wheels错误，根源是编译依赖的mysql.h文件缺失——这个文件属于MySQL开发库组件，默认不会随MySQL Server一起安装。

优先解决方法（无需编译，最简单） #

直接安装预编译好的mysqlclient版本，跳过本地编译环节：

• 打开命令提示符（CMD）或PowerShell
• 执行以下命令：

pip install mysqlclient --only-binary :all:

这条命令会直接下载已经编译完成的安装包，完全不需要mysql.h文件，适合非技术背景用户。

备用解决方法（若预编译版本失效） #

如果上面的命令无法执行，就手动安装MySQL开发库来提供mysql.h文件：

1. 下载对应Windows 64位的MySQL Connector C安装包（版本选8.0系列），安装后记住你的安装路径（默认路径一般是C:\Program Files\MySQL\MySQL Connector C 8.0）
2. 设置系统环境变量：
   • 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
   • 在「系统变量」区域点击「新建」：
     • 变量名填MYSQLCLIENT_CFLAGS，变量值填-I你的安装路径\include（例如-IC:\Program Files\MySQL\MySQL Connector C 8.0\include）
     • 再新建变量MYSQLCLIENT_LDFLAGS，变量值填-L你的安装路径\lib64（例如-LC:\Program Files\MySQL\MySQL Connector C 8.0\lib64）
3. 关闭所有已打开的命令提示符/PowerShell，重新打开后执行：

pip install mysqlclient

你提供的安装日志 #

Downloading mysqlclient-2.2.0.tar.gz (89 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━ 89.5/89.5 kB 211.5 kB/s eta 0:00:00
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: mysqlclient
  Building wheel for mysqlclient (pyproject.toml) ... error
  error: subprocess-exited-with-error

  × Building wheel for mysqlclient (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [46 lines of output]
      # Options for building extention module:
        library_dirs: ['C:/mariadb-connector\\lib\\mariadb', 'C:/mariadb-connector\\lib']
        libraries: ['kernel32', 'advapi32', 'wsock32', 'shlwapi', 'Ws2_32', 'crypt32', 'secur32', 'bcrypt', 'mariadbclient']
        extra_link_args: ['/MANIFEST']
        include_dirs: ['C:/mariadb-connector\\include\\mariadb', 'C:/mariadb-connector\\include']
        extra_objects: []
        define_macros: [('version_info', (2, 2, 0, 'final', 0)), ('__version__', '2.2.0')]
      running bdist_wheel
      running build
      running build_py
      creating build
      creating build\lib.win-amd64-cpython-312
      creating build\lib.win-amd64-cpython-312\MySQLdb
      copying src\MySQLdb\connections.py -> build\lib.win-amd64-cpython-312\MySQLdb
      copying src\MySQLdb\converters.py -> build\lib.win-amd64-cpython-312\MySQLdb
      copying src\MySQLdb\cursors.py -> build\lib.win-amd64-cpython-312\MySQLdb
      copying src\MySQLdb\release.py -> build\lib.win-amd64-cpython-312\MySQLdb
      copying src\MySQLdb\times.py -> build\lib.win-amd64-cpython-312\MySQLdb
      copying src\MySQLdb\_exceptions.py -> build\lib.win-amd64-cpython-312\MySQLdb
      copying src\MySQLdb\__init__.py -> build\lib.win-amd64-cpython-312\MySQLdb
      creating build\lib.win-amd64-cpython-312\MySQLdb\constants   
      copying src\MySQLdb\constants\CLIENT.py -> build\lib.win-amd64-cpython-312\MySQLdb\constants
      copying src\MySQLdb\constants\CR.py -> build\lib.win-amd64-cpython-312\MySQLdb\constants
      copying src\MySQLdb\constants\ER.py -> build\lib.win-amd64-cpython-312\MySQLdb\constants
      copying src\MySQLdb\constants\FIELD_TYPE.py -> build\lib.win-amd64-cpython-312\MySQLdb\constants
      copying src\MySQLdb\constants\FLAG.py -> build\lib.win-amd64-cpython-312\MySQLdb\constants
      copying src\MySQLdb\constants\__init__.py -> build\lib.win-amd64-cpython-312\MySQLdb\constants
      running egg_info
      writing src\mysqlclient.egg-info\PKG-INFO
      writing dependency_links to src\mysqlclient.egg-info\dependency_links.txt
      writing top-level names to src\mysqlclient.egg-info\top_level.txt
      reading manifest file 'src\mysqlclient.egg-info\SOURCES.txt' 
      reading manifest template 'MANIFEST.in'
      adding license file 'LICENSE'
      writing manifest file 'src\mysqlclient.egg-info\SOURCES.txt' 
      copying src\MySQLdb\_mysql.c -> build\lib.win-amd64-cpython-312\MySQLdb
      running build_ext
      building 'MySQLdb._mysql' extension
      creating build\temp.win-amd64-cpython-312
      creating build\temp.win-amd64-cpython-312\Release
      creating build\temp.win-amd64-cpython-312\Release\src        
      creating build\temp.win-amd64-cpython-312\Release\src\MySQLdb
      "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 "-Dversion_info=(2, 2, 0, 'final', 0)" -D__version__=2.2.0 -IC:/mariadb-connector\include\mariadb -IC:/mariadb-connector\include -Ic:\Users\mikai\AppData\Local\Programs\Python\Python312\include -Ic:\Users\mikai\AppData\Local\Programs\Python\Python312\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/MySQLdb/_mysql.c /Fobuild\temp.win-amd64-cpython-312\Release\src/MySQLdb/_mysql.obj
      _mysql.c
      src/MySQLdb/_mysql.c(29): fatal error C1083: Cannot open include file: 'mysql.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 mysqlclient
Failed to build mysqlclient
ERROR: Could not build wheels for mysqlclient, which is required to install pyproject.toml-based projects

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