PyMySQL是纯Python编写的轻量级MySQL驱动，兼容DB-API 2.0，无需编译、跨平台友好，适合受限环境及CI/CD；默认推荐用'127.0.0.1'而非'localhost'，需显式设charset='utf8mb4'，autocommit=True可避免手动commit，建议搭配DictCursor使用。
PyMySQL 是一个纯 Python 编写的 MySQL 客户端驱动库，它完全兼容 Python DB-API 2.0 规范，不需要编译安装（无 C 依赖），开箱即用，特别适合在受限环境（如某些容器、Windows 精简版、或无法安装 mysql-client 开发包的系统）中连接 MySQL。
它不是 MySQL 官方出品（官方推荐的是 mysql-connector-python），但因轻量、稳定、社区活跃，已成为 Python 中最常用的 MySQL 驱动之一，尤其在 Django、Flask、Airflow 等框架中被广泛默认或可选集成。
为什么选 PyMySQL 而不是 mysql-connector-python？
这不是“谁更好”，而是“谁更适配你的场景”：
-
PyMySQL是纯 Python 实现，安装快（pip install PyMySQL）、跨平台零编译问题，对新手和 CI/CD 流水线友好； -
mysql-connector-python是 Oracle 官方维护，支持更多企业级特性（如 X Protocol、连接池高级配置），但默认启用caching_sha2_password插件 —— 这在 MySQL 8.0+ 上常导致Authentication plugin 'caching_sha2_password' cannot be loaded错误，需额外改用户认证方式； - 如果你用的是 MySQL 5.7 或 MariaDB，两者行为基本一致；但若用 MySQL 8.0+ 且不想动服务端配置，
PyMySQL通常“连上就跑”，省心； - Django 默认支持
PyMySQL，只需在项目入口加两行就能替换原生MySQLdb（Python 3 已不维护）：
import pymysql pymysql.install_as_MySQLdb()
PyMySQL 连接 MySQL 的最小可行代码
以下是最简连接示例，含必要参数与常见避坑点：
立即学习“Python免费学习笔记（深入）”；
-
host和port：本地 MySQL 默认是'localhost'+3306，但注意：'localhost'在 PyMySQL 中会触发 Unix socket 连接（可能失败），建议统一用'127.0.0.1'； -
charset必须显式指定（如'utf8mb4'），否则中文插入可能乱码或报Incorrect string value； -
autocommit=False是默认行为，意味着INSERT/UPDATE/DELETE后必须手动调用conn.commit()，否则事务不生效； - 不要省略
cursorclass—— 若想返回字典而非元组，加cursorclass=pymysql.cursors.DictCursor；
import pymysqlconn = pymysql.connect( host='127.0.0.1', port=3306, user='root', password='your_password', database='test_db', charset='utf8mb4', autocommit=True, # 避免忘记 commit cursorclass=pymysql.cursors.DictCursor )
cursor = conn.cursor() cursor.execute("SELECT VERSION()") print(cursor.fetchone()) # {'VERSION()': '8.0.33'}
conn.close()
PyMySQL 常见报错及对应解法
这些错误几乎每个新手都会撞上，原因清晰，修复也直接：
-
ModuleNotFoundError: No module named 'pymysql'→ 检查是否在正确 Python 环境下执行pip install PyMySQL（尤其用 conda 或 virtualenv 时）； -
ConnectionRefusedError: [Errno 111] Connection refused→ MySQL 服务没启动，运行sudo service mysql start（Linux）或检查 Windows 服务里MySQL80是否运行； -
Access denied for user 'root'@'127.0.0.1'→ 密码错，或该用户没从127.0.0.1登录权限（MySQL 默认'root'@'localhost'不等价于'root'@'127.0.0.1'），需执行：CREATE USER 'root'@'127.0.0.1' IDENTIFIED BY 'xxx'; GRANT ALL ON *.* TO 'root'@'127.0.0.1'; FLUSH PRIVILEGES;； -
OperationalError: (1366, "Incorrect string value: '\\xF0\\x9F\\x98\\x8A'...")→ 表/列字符集不是utf8mb4，建表语句末尾加ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci；
真正容易被忽略的，是连接复用和连接泄漏。PyMySQL 不自带连接池，短生命周期脚本无所谓，但 Web 服务中务必用 pymysqlpool 或 SQLAlchemy 管理连接，否则并发一高，MySQL 很快报 Too many connections。
