ubuntu24.04 pip3 install pymysql_utils报错解决

root@ubuntuserver1:~# pip3 install pymysql_utils
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

错误是在安装 pymysql_utils 时，其依赖的 mysqlclient 包在编译过程中无法找到 pkg-config 工具，导致构建失败。这是一个常见的在 Linux 系统上安装 mysqlclient 时遇到的问题，尤其是在缺少必要的开发依赖包的情况下。

🔍 错误原因分析

错误信息中的关键部分是：

/bin/sh: line 1: pkg-config: command not found
…
Exception: Can not find valid pkg-config name.
Specify MYSQLCLIENT_CFLAGS and MYSQLCLIENT_LDFLAGS env vars manually

这说明：

• mysqlclient 是一个需要编译的 Python 包，它依赖于 MySQL 的 C 库（如 libmysqlclient）。

• 编译过程中需要 pkg-config 工具来查找 MySQL 的头文件和库路径。

• 你的系统中缺少 pkg-config 以及 MySQL 的开发依赖包。

✅ 解决方案

你需要在 Ubuntu 系统上安装构建 mysqlclient 所需的开发依赖包，包括 pkg-config 和 MySQL 的开发库。

1️⃣ 安装 pkg-config

sudo apt update
sudo apt install pkg-config

2️⃣ 安装 MySQL 开发依赖包

sudo apt install libmysqlclient-dev default-libmysqlclient-dev

注意：default-libmysqlclient-dev 是 Ubuntu 中包含 libmysqlclient-dev 的一个元包，安装它会自动包含相关依赖。

如果你使用的是 MariaDB 而不是 MySQL，可以安装：
sudo apt install libmariadb-dev libmariadb-dev-compat

3️⃣ 重新安装 pymysql_utils

在安装完上述依赖后，重新运行你的安装命令：
pip install pymysql_utils –break-system-packages

或者更推荐的方式是使用虚拟环境（避免使用 –break-system-packages）：
python -m venv myenv
source myenv/bin/activate
pip install pymysql_utils

❓ 为什么需要这些依赖？

• pkg-config 是一个帮助编译器找到库文件和头文件的工具。

• libmysqlclient-dev 包含了 MySQL C 客户端库的头文件和静态/动态链接库，是编译 mysqlclient 所必需的。