Linux系统Python调用mysql.connector报ModuleNotFoundError问题咨询

算力阿峰

2026-8-30

报错核心原因

出现ModuleNotFoundError: No module named 'mysql.connector'; 'mysql' is not a package报错，基本是以下三类问题导致：

安装了错误的冲突包：PyPI上存在名为mysql的无关第三方包，和Oracle官方的MySQL Python驱动完全不兼容，一旦误装，Python导入时会优先识别这个无效包，无法找到connector子模块。
Python环境不匹配：Linux系统通常预装多版本Python（Python2/Python3共存），或是存在虚拟环境、conda环境与全局环境混用的情况，你把驱动装到了非当前运行代码的Python环境中，解释器自然找不到对应模块。
本地同名文件覆盖：运行Python脚本的工作目录下，存在命名为mysql.py的文件，或是名为mysql的自定义文件夹，Python导入模块时会优先加载当前工作目录的内容，直接覆盖官方安装的mysql包，触发识别错误。

mysql.connector模块报错截图

分步解决方法

卸载所有冲突的无效包
针对你使用的Python版本，执行命令卸载已安装的错误包，避免残留冲突：
```
# 同时清理pip和pip3下的冲突包
pip uninstall -y mysql mysql-connector
pip3 uninstall -y mysql mysql-connector
```
排查本地同名文件干扰
进入你运行Python脚本的目录，检查是否存在mysql.py文件或mysql命名的文件夹，如果存在直接重命名为非模块名的其他名称，同时删除目录下自动生成的__pycache__缓存文件夹，清除旧导入缓存的影响。

匹配当前环境安装官方驱动
一定要用你运行代码时调用的Python解释器来执行安装，避免环境错配，最稳妥的安装方式是直接调用解释器本身执行pip安装：

# 如果你平时用python3命令跑脚本，就执行这条
python3 -m pip install mysql-connector-python
# 如果你用的是虚拟环境/conda环境，先激活对应环境后，再执行python -m pip install mysql-connector-python即可

验证修复结果
执行以下验证命令，如果正常输出版本号、无报错，说明问题已经解决：
```
python3 -c "import mysql.connector; print('驱动加载正常，当前版本：', mysql.connector.__version__)"
```

注意：不要用pip install mysql-connector安装旧版非官方驱动，这个包已经长期停更，和新版Python3存在兼容性问题，优先安装官方维护的mysql-connector-python包。

内容的提问来源于stack exchange，提问作者Alfred Joe Jr