Mac环境pip install mariadb安装失败报错问题求助

问题描述 #

开发Web应用需通过Python连接MariaDB数据库，当前运行环境为搭载Python 3.7.9版本的Mac设备，执行pip install mariadb命令安装官方Python驱动时出现安装失败，完整报错信息如下：

Collecting mariadb
  Using cached mariadb-1.0.11.zip (85 kB)
Using legacy setup.py install for mariadb, since package 'wheel' is not installed.
Installing collected packages: mariadb
    Running setup.py install for mariadb ... error
    ERROR: Command errored out with exit status 1:
     command: /Users/.../bin/python -u -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/private/var/folders/yz/_pkhkb0x2xb233lq1n0v193r0000gp/T/pip-install-yeefaepy/mariadb/setup.py'"'"'; __file__='"'"'/private/var/folders/yz/_pkhkb0x2xb233lq1n0v193r0000gp/T/pip-install-yeefaepy/mariadb/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' install --record /private/var/folders/yz/_pkhkb0x2xb233lq1n0v193r0000gp/T/pip-record-ock6ntv0/install-record.txt --single-version-externally-managed --compile --install-headers /Users/.../include/site/python3.7/mariadb
         cwd: /private/var/folders/yz/_pkhkb0x2xb233lq1n0v193r0000gp/T/pip-install-yeefaepy/mariadb/
    Complete output (46 lines):
    10.6.8
    running install
    running build
    running build_py
    creating build
    creating build/lib.macosx-10.9-x86_64-3.7
    creating build/lib.macosx-10.9-x86_64-3.7/mariadb
    copying mariadb/__init__.py -> build/lib.macosx-10.9-x86_64-3.7/mariadb
    creating build/lib.macosx-10.9-x86_64-3.7/mariadb/constants
    copying mariadb/constants/__init__.py -> build/lib.macosx-10.9-x86_64-3.7/mariadb/constants
    copying mariadb/constants/CLIENT.py -> build/lib.macosx-10.9-x86_64-3.7/mariadb/constants
    copying mariadb/constants/INDICATOR.py -> build/lib.macosx-10.9-x86_64-3.7/mariadb/constants
    copying mariadb/constants/CURSOR.py -> build/lib.macosx-10.9-x86_64-3.7/mariadb/constants
    copying mariadb/constants/FIELD_TYPE.py -> build/lib.macosx-10.9-x86_64-3.7/mariadb/constants
    running build_ext
    building 'mariadb._mariadb' extension
    creating build/temp.macosx-10.9-x86_64-3.7
    creating build/temp.macosx-10.9-x86_64-3.7/mariadb
    gcc -Wno-unused-result -Wsign-compare -Wunreachable-code -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes -I/Users/.../include -arch x86_64 -I/Users/MitchPudill/opt/anaconda3/include -arch x86_64 -DPY_MARIADB_MAJOR_VERSION=1 -DPY_MARIADB_MINOR_VERSION=0 -DPY_MARIADB_PATCH_VERSION=11 -I/usr/local/Cellar/mariadb-connector-c/3.3.1/include/mariadb -I/usr/local/Cellar/mariadb-connector-c/3.3.1/include/mariadb/mysql -I./include -I/Users/.../include -I/Users/.../opt/anaconda3/include/python3.7m -c mariadb/mariadb.c -o build/temp.macosx-10.9-x86_64-3.7/mariadb/mariadb.o -DDEFAULT_PLUGINS_SUBDIR="/usr/local/Cellar/mariadb-connector-c/3.3.1/lib/mariadb/plugin"
    In file included from mariadb/mariadb.c:21:
    ./include/mariadb_python.h:75:2: error: Minimum required version of MariaDB Connector/C is 3.1.3
    #error Minimum required version of MariaDB Connector/C is 3.1.3
     ^
    ./include/mariadb_python.h:244:30: error: field has incomplete type 'enum enum_indicator_type'
        enum enum_indicator_type indicator;
                                 ^
    ./include/mariadb_python.h:244:10: note: forward declaration of 'enum enum_indicator_type'
        enum enum_indicator_type indicator;
             ^
    ./include/mariadb_python.h:297:5: error: unknown type name 'ps_field_fetch_func'
        ps_field_fetch_func func;
        ^
    mariadb/mariadb.c:273:45: error: use of undeclared identifier 'STMT_INDICATOR_NULL'
                           MrdbIndicator_Object(STMT_INDICATOR_NULL));
                                                ^
    mariadb/mariadb.c:275:45: error: use of undeclared identifier 'STMT_INDICATOR_DEFAULT'
                           MrdbIndicator_Object(STMT_INDICATOR_DEFAULT));
                                                ^
    mariadb/mariadb.c:277:45: error: use of undeclared identifier 'STMT_INDICATOR_IGNORE'
                           MrdbIndicator_Object(STMT_INDICATOR_IGNORE));
                                                ^
    mariadb/mariadb.c:279:45: error: use of undeclared identifier 'STMT_INDICATOR_IGNORE_ROW'
                           MrdbIndicator_Object(STMT_INDICATOR_IGNORE_ROW));
                                                ^
    7 errors generated.
    error: command 'gcc' failed with exit status 1
    ----------------------------------------
ERROR: Command errored out with exit status 1: /Users/.../bin/python -u -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/private/var/folders/yz/_pkhkb0x2xb233lq1n0v193r0000gp/T/pip-install-yeefaepy/mariadb/setup.py'"'"'; __file__='"'"'/private/var/folders/yz/_pkhkb0x2xb233lq1n0v193r0000gp/T/pip-install-yeefaepy/mariadb/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' install --record /private/var/folders/yz/_pkhkb0x2xb233lq1n0v193r0000gp/T/pip-record-ock6ntv0/install-record.txt --single-version-externally-managed --compile --install-headers /Users/.../include/site/python3.7/mariadb Check the logs for full command output.

已尝试以下排查操作均未解决问题：

• 新建独立虚拟环境执行安装，问题复现
• 切换多个不同Python版本执行安装，问题复现
• 执行brew install mariadb-connector-c，系统提示mariadb-connector-c 3.3.1已安装且为最新版本
• 尝试执行brew install libmariadb-dev与brew install libmariadb3，Homebrew提示无对应可用安装公式
• 执行brew install mariadb完成服务端安装，仍无法解决Python包安装报错问题
• 尝试安装多个近期发布的mariadb Python包版本，问题依旧存在
• 执行brew unlink mariadb后重新link mariadb-connector-c，操作可正常完成但问题未解决

故障原因 #

报错核心是两个叠加问题：

1. 安装的mariadb Python 1.0.11版本和Homebrew默认提供的mariadb-connector-c 3.3.1版本存在头文件结构兼容问题，3.3.x版本调整了部分枚举、类型定义的位置，1.0.x系列驱动未做适配
2. 系统路径中残留有更早版本的MariaDB Connector/C头文件，编译时gcc优先读取了旧头文件，触发了「最低要求3.1.3版本」的版本校验报错，后续的类型未定义、常量未找到错误都是这两个问题引发的连锁编译失败。

解决步骤 #

按顺序执行以下命令即可完成安装：

1. 彻底清理现有残留的MariaDB相关文件，避免旧文件干扰编译

brew uninstall --force mariadb mariadb-connector-c
sudo rm -rf /usr/local/include/mariadb /usr/local/include/mysql* /usr/local/lib/libmariadb* /usr/local/bin/mariadb_config

2. 安装和1.0.x系列驱动兼容的mariadb-connector-c 3.1.14稳定版本，Homebrew默认源没有旧版本，通过本地tap安装指定版本

brew tap-new local/mariadb
brew extract --version=3.1.14 mariadb-connector-c local/mariadb
brew install local/mariadb/mariadb-connector-c@3.1.14
brew link --force mariadb-connector-c@3.1.14

3. 升级pip基础组件，避免走旧版setup.py安装逻辑

pip install --upgrade pip setuptools wheel

4. 指定mariadb_config路径后安装Python驱动，确保编译时读取到正确版本的头文件和库配置

export MARIADB_CONFIG=/usr/local/opt/mariadb-connector-c@3.1.14/bin/mariadb_config
pip install mariadb==1.0.11

5. 验证安装：进入Python交互环境执行import mariadb，无报错即安装成功。

补充说明：如果后续要升级mariadb Python包到1.1.0及以上版本，再对应将mariadb-connector-c升级到3.2.x版本即可，不要在1.0.x驱动版本下搭配3.3.x连接器使用。

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