Python连接MySQL驱动安装指南：直接装mysql-connector-python，别用mysql-connector
在Python项目中配置MySQL数据库连接，第一步选择正确的驱动包至关重要。许多开发者首次尝试时就会遇到安装失败或连接报错的问题。请牢记这个核心解决方案：务必直接安装 mysql-connector-python，切勿使用已被弃用的 mysql-connector。后者是过时的旧包名，不仅容易导致pip安装出错或版本混乱，更是连接MySQL 8.0及以上版本失败的主要原因。
正确选择是安装mysql-connector-python而非mysql-connector，因为后者已停止维护且无法支持MySQL 8.0+默认的caching_sha2_password加密认证；标准安装命令为pip3 install mysql-connector-python，安装后需确认版本号不低于8.4.0。
为什么pip install mysql-connector会失败或无法连接MySQL 8.0+数据库
当你在Python中遇到 ModuleNotFoundError: No module named 'mysql.connector' 导入错误，或者在建立连接时收到 Authentication plugin 'caching_sha2_password' is not supported 的提示，问题通常不在你的代码逻辑。根源在于驱动包的选择错误：
- 不带
-python后缀的mysql-connector是一个非官方的、已过时的第三方包。它已在PyPI仓库中下架，使用pip安装时要么直接失败，要么安装一个无法正常工作的空包，导致无法导入。 - 关键原因在于，MySQL数据库从8.0版本起，默认采用了更安全的
caching_sha2_password身份验证插件。而旧的、不完整的驱动包根本不支持这个新插件，因此连接必然失败。
幸运的是，官方持续维护的 mysql-connector-python 驱动已原生支持这一新认证机制。你无需为了连接成功而降低MySQL服务器的安全配置等级。
正确的安装命令与版本验证步骤
安装过程非常简单。打开命令行终端，执行以下命令（建议明确使用 pip3，以避免Python 2与Python 3环境可能产生的混淆）：
pip3 install mysql-connector-python
安装完成后，如何确认安装正确且版本合适？通过一个快速的Python命令进行验证：
python3 -c "import mysql.connector; print(mysql.connector.__version__)"
如果终端显示出版本号，例如 8.4.0 或更高（截至2026年，主流稳定版本为8.4.x系列），则表明安装成功。如果此处出现 ImportError，很可能误装了错误的包。建议先使用 pip3 uninstall mysql-connector mysql-connector-python 彻底清理，再重新安装正确的包。
立即学习“Python免费学习笔记（深入）”；
连接MySQL 8.0+时是否需要手动指定auth_plugin参数
这是另一个常见的技术疑问。答案是：在绝大多数标准场景下，你不需要手动设置 auth_plugin 参数。 新版驱动足够智能，能够自动与MySQL 8.0+服务器协商，使用默认的 caching_sha2_password 插件完成身份验证。
仅在少数特殊环境，例如特定的Docker容器镜像或经过自定义编译的MySQL服务出现认证失败时，才可能需要临时指定：
- 在连接配置中显式指定旧的认证插件：
auth_plugin='mysql_native_password'。 - 但必须注意，MySQL Server 8.4.0版本已默认禁用
mysql_native_password插件，并计划在未来的9.0+版本中彻底移除。在代码中硬编码此参数，将为后续升级留下兼容性隐患。 - 更根本、一劳永逸的解决方法是修复服务端配置。使用root账户登录MySQL，执行类似
ALTER USER 'your_username'@'%' IDENTIFIED WITH caching_sha2_password BY 'your_password';的SQL语句，确保用户账户使用的是服务器支持的认证方式。
连接代码中database参数为空或指定不存在的数据库会怎样
database 参数在连接时是可选的，但其设置状态将直接影响后续的数据库操作：
- 参数留空：例如使用
mysql.connector.connect(host='localhost', user='root', password='123456')连接，你会成功连接到MySQL服务器实例，但处于未选择具体数据库的状态。这意味着之后执行的所有SQL查询，都必须使用数据库全限定名称，例如SELECT * FROM my_database.users。 - 指定了不存在的数据库：如果你设置了
database='non_existent_db'，连接器将直接抛出mysql.connector.errors.ProgrammingError: 1049 (42000): Unknown database 'non_existent_db'错误，连接会失败，而不会忽略此参数建立连接。 - 那么，如何先建立连接再安全地判断目标数据库是否存在？可以采用两步法：首先，不指定
database参数建立连接；然后，使用游标执行cursor.execute("SHOW DATABASES LIKE 'target_db'")进行查询。根据返回结果，再决定是创建新数据库还是切换到该数据库进行连接。
此外，一个容易被忽视的细节是驱动版本与MySQL服务器版本之间的隐性兼容问题。例如，使用 mysql-connector-python 8.0.33 连接 MySQL 8.4 服务器，有时可能引发预料之外的认证协商失败。因此，一个通用的最佳实践是：尽量将Python连接器驱动保持为最新的稳定版本。截至2026年4月，推荐版本即为 8.4.0。保持驱动更新，可以有效规避许多历史遗留的兼容性“暗坑”。
