如何解决 pip install mysqlclient 报错 ‘mysql_config’ not found 问题

Python系列Bug修复PyCharm控制台pip install报错：如何解决 pip install mysqlclient 报错 'mysql_config' not found 问题

---

摘要

在 Python Web / 数据库开发过程中，使用 PyCharm 控制台通过 pip 安装第三方库 是再常见不过的操作了。但不少同学在执行
pip install mysqlclient

时，会直接被一个经典又"劝退"的错误拦住：

❌ error: mysql_config not found

这个问题在 macOS + PyCharm + Python3 的开发环境下尤为常见，初学者甚至有一定经验的开发者都可能中招。

文章目录

• [Python系列Bug修复PyCharm控制台pip install报错：如何解决 pip install mysqlclient 报错 'mysql_config' not found 问题](#Python系列Bug修复PyCharm控制台pip install报错：如何解决 pip install mysqlclient 报错 'mysql_config' not found 问题)
• • 摘要
  • 一、问题背景：这个异常通常出现在什么开发场景？
  • • 常见开发场景举例
  • 二、开发环境说明（问题高发环境）
  • [三、pip install mysqlclient 报错的本质原因分析](#三、pip install mysqlclient 报错的本质原因分析)
  • • [3.1 mysqlclient 并不是纯 Python 包](#3.1 mysqlclient 并不是纯 Python 包)
  • 四、真实问题解决流程
  • [五、核心解决方案（逐条拆解 + 扩展）](#五、核心解决方案（逐条拆解 + 扩展）)
  • • [5.1 module 包没安装 / 包名写错](#5.1 module 包没安装 / 包名写错)
    • [5.2 网络问题：切换国内 pip 镜像源（强烈推荐）](#5.2 网络问题：切换国内 pip 镜像源（强烈推荐）)
    • • 临时使用清华源
      • [永久配置 pip 镜像源](#永久配置 pip 镜像源)
      • • [macOS / Linux：`pip.conf`](#macOS / Linux：pip.conf)
        • Windows：`pip.ini`
    • [5.3 pip 版本过低（隐藏大坑）](#5.3 pip 版本过低（隐藏大坑）)
    • [5.4 系统未安装 MySQL / mysql_config 不存在（最常见）](#5.4 系统未安装 MySQL / mysql_config 不存在（最常见）)
    • • [macOS 使用 Homebrew 安装](#macOS 使用 Homebrew 安装)
    • [5.5 忘了 import（低级但真实）](#5.5 忘了 import（低级但真实）)
    • [5.6 缺少 `init.py` 文件](#5.6 缺少 __init__.py 文件)
    • [5.7 package 版本不兼容](#5.7 package 版本不兼容)
    • [5.8 自定义包名与第三方包名冲突](#5.8 自定义包名与第三方包名冲突)
    • [5.9 PYTHONPATH 未设置 / 路径不正确](#5.9 PYTHONPATH 未设置 / 路径不正确)
    • [5.10 不恰当使用相对导入](#5.10 不恰当使用相对导入)
  • [六、pip install 问题速查总结表（强烈收藏 ⭐）](#六、pip install 问题速查总结表（强烈收藏 ⭐）)
  • 最佳实践建议（避免以后再踩坑）
  • [温馨提示 🔔](#温馨提示 🔔)
  • 作者✍️名片

---

---

一、问题背景：这个异常通常出现在什么开发场景？

在如下典型场景中，问题极易出现：

• 使用 PyCharm 自带 Terminal / Python Console
• 在 macOS 系统中
• Python 项目需要连接 MySQL 数据库
• 执行命令：

pip install mysqlclient

结果却出现类似错误：

❌ mysql_config not found

❌ subprocess-exited-with-error

❌ legacy-install-failure

常见开发场景举例

我正在开发一个 Django / Flask 项目，需要使用 MySQL，按照教程安装 mysqlclient，结果在 PyCharm 里直接报错，看不懂，也不知道从哪下手。

---

二、开发环境说明（问题高发环境）

为了方便大家对号入座，先明确本文的 实验与高发环境：

环境项	版本
操作系统	macOS（Intel / Apple Silicon 均可能）
Python	Python 3.x
IDE	PyCharm 2025
包管理工具	pip
数据库	MySQL / MariaDB

---

三、pip install mysqlclient 报错的本质原因分析

3.1 mysqlclient 并不是纯 Python 包

mysqlclient 是一个 C 扩展包，安装时需要：

• MySQL 客户端开发库
• mysql_config 可执行文件

如果系统中 没有安装 MySQL 或未配置环境变量，pip 自然会失败。

---

四、真实问题解决流程

MySQL客户端 操作系统 pip 开发者 MySQL客户端 操作系统 pip 开发者 pip install mysqlclient 查找 mysql_config 未找到 报错 mysql_config not found 安装 MySQL 客户端 配置 PATH 重新 pip install 安装成功

---

五、核心解决方案（逐条拆解 + 扩展）

5.1 module 包没安装 / 包名写错

确认你安装的是 mysqlclient，而不是：

pip install mysql-client   # ❌ 错误
pip install MySQLClient    # ❌ 不推荐

✅ 正确命令：

pip install mysqlclient

---

5.2 网络问题：切换国内 pip 镜像源（强烈推荐）

国内网络环境下，pip 安装失败极其常见。

临时使用清华源

pip install mysqlclient -i https://pypi.tuna.tsinghua.edu.cn/simple

永久配置 pip 镜像源

macOS / Linux：pip.conf

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

路径：

~/.pip/pip.conf

Windows：pip.ini

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

---

5.3 pip 版本过低（隐藏大坑）

pip install --upgrade pip

---

5.4 系统未安装 MySQL / mysql_config 不存在（最常见）

macOS 使用 Homebrew 安装

brew install mysql

确认是否存在：

which mysql_config

若不存在，手动添加 PATH：

export PATH="/usr/local/opt/mysql/bin:$PATH"

---

5.5 忘了 import（低级但真实）

import MySQLdb

而不是只安装不使用。

---

5.6 缺少 __init__.py 文件

如果你在 自建包中导入 mysqlclient，务必保证：

your_package/
 ├── __init__.py
 └── db.py

---

5.7 package 版本不兼容

某些 Python 版本下需指定版本：

pip install mysqlclient==2.1.1

---

5.8 自定义包名与第三方包名冲突

❌ 错误示例：

mysqlclient.py

会导致：

import mysqlclient  # 实际导入的是你自己的文件

---

5.9 PYTHONPATH 未设置 / 路径不正确

echo $PYTHONPATH

必要时：

export PYTHONPATH=/your/project/path

---

5.10 不恰当使用相对导入

❌：

from ..db import connect

在非包环境下运行会直接报错。

---

六、pip install 问题速查总结表（强烈收藏 ⭐）

问题类型	解决方式
包未安装	pip install
包名错误	校对 PyPI 名称
网络异常	切换国内源
pip 版本低	pip install -U pip
mysql_config 不存在	安装 MySQL
PATH 未配置	export PATH
版本冲突	指定版本
包名冲突	重命名文件
PYTHONPATH 错误	配置环境变量

---

---

最佳实践建议（避免以后再踩坑）

• ✅ 优先使用虚拟环境（venv / conda）
• ✅ 新项目先升级 pip
• ✅ 数据库驱动类包优先查官方文档
• ✅ PyCharm 中确认解释器路径一致

---

温馨提示 🔔

更多 Bug 解决方案请查看==> 全栈Bug解决方案专栏

👉 https://blog.csdn.net/lyzybbs/category_12988910.html

---

作者✍️名片

---

如果你在 pip / PyCharm / Python / 环境配置 上还有其他疑难杂症，欢迎评论区交流，一起少掉头发，多写代码 😄🐍