简介：matplotlib-3.7.0源码压缩包是Python数据可视化库的完整发行版，面向需要绘制专业图表的科研、数据分析与开发人群，尤其适合具备一定Python基础、希望深入理解绘图原理或进行二次开发与离线部署的中高级使用者。包内共2000个文件，包括九百余个Python模块源文件、六百余份PDF文档、一百六十个C语言头文件和五十八个C++源文件，以及大量PNG、SVG图片和TXT说明等，其中PDF文档以官方说明和API参考为主，图片资源多用于示例与文档展示，总大小34.66MB，目录结构清晰完整。目前已有191人学习下载。解压后可以完整查阅绘图接口的Python实现、底层C/C++扩展代码、各类图表对应源码与测试样例，既能支持无网络环境下的安装使用，也能借鉴其架构设计来定制自己的可视化逻辑，是一份深入掌握matplotlib不可多得的参考资料。 在数据分析这个行当里摸爬滚打久了，总会遇到一些让人哭笑不得的场景：明明项目在本地跑得好好的，一到现场就变成"离线环境装不了包"；明明pip install matplotlib一句话的事，偏偏摆在你面前的只有一个孤零零的matplotlib-3.7.0.tar.gz压缩包。这篇东西就是写给正在跟这个压缩包较劲的人看的——我会把这个包是什么、为什么非要用它、离线编译安装时有哪些坑、装完之后那个"请安装 matplotlib 以显示图标"又是怎么回事，一条龙说清楚，最后再带你画出安装成功后的第一张图。
1. 拿到 matplotlib-3.7.0.tar.gz，先搞清楚它是谁
很多人看到.tar.gz结尾的文件就头疼，其实把文件名拆开看就明朗了：matplotlib是库名，3.7.0是版本号，.tar.gz是打包格式，这种包在 Python 世界里有个正式称呼叫sdist（源码发行版）。跟它相对的，是平时pip install默认下载的.whl格式 wheel 包，两者最大的区别在于：wheel 是已经编译好的二进制文件，下载解压就能用；而 sdist 是源代码，需要在你自己的机器上编译一遍才能安装。
那有人会问了：既然 wheel 这么省事，为什么还要发布tar.gz？原因有三。第一，PyPI 上并非所有平台都有对应的 wheel 包，比如一些冷门的 Linux 架构、ARM 板子或者老的 macOS 系统，官方没有提供预编译产物，源码包就是唯一的官方安装途径。第二，有些企业内部源或内网镜像只同步了 sdist 类型文件，你没得选。第三，源码包支持对库进行二次修改，某些定制场景需要改 matplotlib 源码再编译，那也必须用它。
至于3.7.0这个版本，发布于 2023 年初，它相比之前的 3.6 系列有一个很实际的变化：对 Python 3.8 及以上版本的支持更成熟，同时优化了contourpy等高强度绘图组件的依赖逻辑，画等高线图和填充图时性能有提升。它还增加了一套更清晰的样式系统，能用类似plt.style.use('ggplot')的方式快速切换图表风格。如果你是在 2023 年之后拉的老项目，包管理文件里写matplotlib==3.7.0锁定版本，那基本就会跟这个tar.gz撞个正着。
还有一个关键点需要明确：如果你手里只有这个压缩包而没有网，那就意味着所有依赖也得走离线安装。很多人栽跟头就栽在这——以为装一个包就完事了，结果编译到一半提示缺这个缺那个。所以下一节我说的依赖梳理，绝不是走过场。
2. 离线安装最大工程：先把依赖全家桶理清楚
matplotlib 从来不是一个"小而美"的库，它的依赖树相当庞大。3.7.0版要正常工作，至少需要以下这些包：
numpy>=1.20：绘图的数据基础，所有数组运算都靠它contourpy>=1.0.1：等高线计算和绘制，3.x 系列新增的核心依赖cycler>=0.10：颜色循环机制，处理多条曲线的自动配色fonttools>=4.22.0：字体解析，负责文本和图例的字体处理kiwisolver>=1.0.1：约束求解器，主要用于图例、子图布局的尺寸计算packaging>=20.0：版本号校验工具pillow>=6.2.0：图像后端之一，保存 PNG 等图片格式必须pyparsing>=2.3.1：文本解析表达式，处理 mathtext 数学公式python-dateutil>=2.7：日期处理，画时间序列图时的坐标轴刻度依赖
这串列表不是摆着好看的。你在离线环境执行编译安装时，只要缺一个依赖，安装过程就可能在某一步直接挂掉，而且报错信息往往不会直接告诉你"缺了哪个"，而是给你一段晦涩难懂的 C 语言编译报错。
我的建议是：先在能联网的机器上把整个依赖树一次性下载好。这一步看似简单，其实有两个必须避开的坑。
第一个坑是版本锁定。千万不要不带版本号直接pip download matplotlib，那样下载下来的可能是当时的最新版，和你手里的 3.7.0 依赖不完全匹配。正确做法是明确指定版本：
# 在有网的机器上，创建目录并下载 matplotlib 3.7.0 及其依赖 mkdir wheelhouse pip download matplotlib==3.7.0 \ --dest wheelhouse \ --only-binary=:all: \ --platform manylinux2014_x86_64 \ --python-version 38第二个坑是平台参数。上面的命令里我写了--platform manylinux2014_x86_64和--python-version 38，这是为了模拟目标环境的系统架构和 Python 版本。如果不带这两个参数，pip download会拉当前机器版本对应的 wheel——假设你在自己的 Mac 上下载，拿到的是 macOS 的 wheel，拷到 Linux 服务器上照样装不了。如果你目标机器没有对应平台的 wheel，那就必须放弃--only-binary=:all:，改用普通下载模式把源码包也一并拉下来：
pip download matplotlib==3.7.0 --dest wheelhouse --no-deps再用pip download matplotlib==3.7.0 --dest wheelhouse --no-binary :all:把依赖的源码包也补齐。两条命令下载完，整个目录拷到内网机器，pip install --no-index --find-links=wheelhouse matplotlib就能开始离线安装了。这套操作我实测过很多次，比一个个手动去 PyPI 网页扒包省事太多。
3. 从源码编译安装 matplotlib-3.7.0：完整链路与报错处置
如果你拿到的只有这一个matplotlib-3.7.0.tar.gz，连依赖也得一起想办法，那唯一的路就是源码编译。先给结论：整个编译安装过程可以分为三步——准备系统库、解压并安装源码包、处理编译报错。
3.1 编译前必须装好的系统级依赖
很多人第一步就栽了。matplotlib 编译时不光需要 Python 的依赖包，还需要操作系统层面的 C 库，主要两个：freetype（字体渲染）和libpng（PNG 图片编码）。在 Debian/Ubuntu 系系统上，先执行：
sudo apt update sudo apt install -y build-essential python3-dev libfreetype6-dev libpng-dev pkg-config在 CentOS/RHEL 或者麒麟等国产 Linux 系统上，对应的是：
sudo yum install -y gcc gcc-c++ python3-devel freetype-devel libpng-devel pkgconfigbuild-essential/gcc提供 C 编译器，python3-dev/python3-devel提供 Python 头文件，没有这两个东西，setup.py 连第一步编译都过不去。pkg-config则负责帮编译过程找到 freetype 和 libpng 的安装位置。
3.2 解压安装的标准流程
系统环境整好之后，把压缩包传进内网机器，接下来就简单了：
tar -xzf matplotlib-3.7.0.tar.gz cd matplotlib-3.7.0 pip install .如果你的 Python 环境里已经有 numpy 了，这条命令执行的其实是"构建 wheel 并安装"的过程。顺利的话，几十分钟后（取决于机器性能，树莓派这类设备可能得两小时）就能看到Successfully installed matplotlib-3.7.0。
需要注意，现在 Python 生态已经全面转向pyproject.toml构建流程，所以不要再用python setup.py install这种老姿势。matplotlib 3.7.0 的源码包虽然带了 setup.py，但官方推荐路径是通过pip install .来触发 PEP 517 构建，这样能自动下载依赖，避免很多兼容性问题——当然离线环境得先把依赖准备到本地才能自动下载成功。
3.3 三个高频编译报错的排查思路
我在离线部署中遇到最多的编译错误，基本集中在下面这三类：
报错一：numpy.distutils相关错误，或者找不到 numpy 头文件
原因：编译过程中需要 numpy 的头文件参与构建，如果环境里没有 numpy 或版本不对，setup.py 会直接中断。解决办法：先装好numpy==1.24（3.7.0 对应的稳妥版本），再回来编译 matplotlib。离线环境就先把 numpy 的 wheel 包下载好传进去。
报错二：fatal error: ft2build.h: No such file or directory
原因：这就是 freetype 没装或者没被找到。freetype 是文本渲染的核心库，matplotlib 的所有文字、刻度标签都靠它。如果确认已经apt install libfreetype6-dev，但还是报这个错，多半是 pkg-config 路劲没识别，可以手动指定环境变量：
export CFLAGS="-I/usr/include/freetype2" pip install .报错三：fatal error: png.h: No such file or directory
原因：libpng 缺失，PNG 图像格式无法支持。装完libpng-dev后重试即可。如果内网环境连 apt 源也没有，那就要提前把 deb 包下载好，用dpkg -i手动安装。
处理编译报错有一个很实用的心态：报错信息永远只看最上面的 Error 而不是最后的堆栈。C 编译器经常在报错之前打印一大堆中间信息，真正的根因往往在第一屏。遇到不认识的报错，先grep -i error过滤日志，再定位是系统库问题还是 Python 包问题，会快得多。
4. "请安装 matplotlib 以显示图标"：装完之后最常见的连环坑
编译安装好不容易成功了，兴冲冲跑项目，结果又遇到一段中文提示："请安装 matplotlib 以显示图标"。这句话在 pandas 绘图、seaborn 和数据挖掘类项目中非常常见，十有八九让人一头雾水——明明刚装上，凭什么还让装？
这个提示的本质是：你当前正在运行的 Python 解释器里，import matplotlib 失败。看起来不可思议，但在真实环境中，原因往往出人意料地简单——你装到了 A 环境，却在 B 环境里运行代码。
最常见的场景是 conda 和 pip 混用。比如你用 conda 创建了一个叫env1的环境，激活后执行了pip install ./matplotlib-3.7.0.tar.gz，安装确实成功了。但你的 Jupyter Notebook 是之前从 base 环境启动的，内核还挂在 base 环境的 Python 上，它自然 import 不到env1里的 matplotlib。pandas 在绘图时检测到 import 失败，就会抛出这个"请安装 matplotlib"的提示。
排查思路很简单，就三步：
# 第一步：确认当前解释器 which python # 第二步：在被调用解释器里验证 matplotlib python -c "import matplotlib; print(matplotlib.__version__, matplotlib.__file__)" # 第三步：确认 pip 装到了哪里 which pip pip list | grep -i matplotlib只要这三步走完，问题基本就定位了。我看过太多人卡在"反复装包"这个死循环里：用系统 pip 装一次，发现没用；换 conda 又装一次，还是没用；最后才发现 Jupyter 内核的 Python 路径和自己的 shell 不一致。解决办法也很简单：要么把 Jupyter 内核切换到已装好 matplotlib 的环境，要么在启动 Jupyter 的那个终端里先conda activate对应环境再启动。
还有一个隐蔽问题：如果你的 Python 是从源码编译安装的，而 pip 是系统自带的老版本，装出来的包路径可能落在系统目录，当前用户没有读取权限，python import 时会静默失败或者抛出用户权限相关的错误。这时候建议直接用当前用户的 pip 装到用户目录：
pip install --user ./matplotlib-3.7.0.tar.gz5. 装好之后的第一张图，以及一些长期实用的绘图习惯
无论你是通过 wheel 离线安装还是源码编译安装，只要python -c "import matplotlib"不报错，就可以开始画图了。我建议第一天就验证最基础的两件事：默认后端能不能正常保存图片、中文字体有没有乱码。
5.1 最快出图的脚本
把下面这段代码存成test_plot.py，跑一下，如果目录下生成了first_plot.png，说明整套环境没问题：
import matplotlib.pyplot as plt import numpy as np x = np.linspace(0, 10, 100) y = np.sin(x) fig, ax = plt.subplots(figsize=(8, 5)) ax.plot(x, y, label="sin(x)", linewidth=2) ax.scatter(x[::10], np.cos(x[::10]), color="red", label="cos(x)", s=30) ax.set_title("Matplotlib 3.7.0 Test") ax.legend() fig.savefig("first_plot.png", dpi=150, bbox_inches="tight")这段代码用了subplots()返回的fig和ax对象，这是现代 matplotlib 推荐的面向对象画法，比老的plt.plot()全局状态模式更适合复杂图表的控制。注意我在savefig里加了bbox_inches="tight"，这个参数会自动裁掉多余白边，导出图片看起来专业很多。dpi=150则是为了屏幕观看的清晰度，如果是要印刷或投稿，通常要 300 以上。
5.2 中文字体乱码的处理
matplotlib 3.7.0 的默认字体是不包含中文字符的，直接画带中文标题的图会出现一堆方块乱码。这是新手的必修坑。解决办法有两个方向：一是指定系统中已有的中文字体，二是下载好看的开源字体（比如思源黑体）放到 matplotlib 字体目录。
我用得最多的是第一个方向，简单有效：
import matplotlib.pyplot as plt plt.rcParams["font.sans-serif"] = ["Noto Sans CJK SC", "SimHei", "Microsoft YaHei"] plt.rcParams["axes.unicode_minus"] = False # 解决负号显示为方块的问题axes.unicode_minus这个参数很容易被忽略。默认情况下 matplotlib 用 Unicode 编码显示负号，很多中文字体里没有这个字符对应的字形，于是坐标轴上的负号全变成方块。把它设为 False，就会用 ASCII 的连字符替代，一劳永逸。
5.3 一套建议大家长期使用的全局样式
在 3.7.0 里，用rcParams统一设置一次，整个项目都能受益。这里分享一组我实测很稳的配置：
import matplotlib.pyplot as plt plt.rcParams.update({ "figure.figsize": (10, 6), "figure.dpi": 100, "font.size": 12, "axes.titlesize": 14, "axes.labelsize": 12, "legend.fontsize": 10, "lines.linewidth": 2, "savefig.dpi": 200, "savefig.bbox": "tight", })这样设置的好处是，日常写分析脚本时不需要每次都调一遍参数，画出来的图大小、字号、清晰度都比较统一。特别是savefig.dpi，很多人画图时忘了指定，默认 100，放到论文或 PPT 里一放大全是马赛克。
根据我个人经验，源码编译安装 matplotlib 这件事，真正难的从来不是那几行安装命令，而是对环境的整体判断：依赖链有没有备齐、解释器路径对不对、编译缺的 C 库装没装、字体配置怎么弄。把这些捋顺了，matplotlib-3.7.0.tar.gz这个压缩包也就是个普普通通的安装文件而已。最后再分享一个小技巧：凡是内网环境装 Python 包，我强烈建议保留一个和现场同版本的有网虚拟机，每次部署前先在虚拟机上pip download完整 wheelhouse，再连同安装脚本一起拷进去，这比现场手工折腾源码包省掉 80% 的时间。
本文还有配套的精品资源，点击获取
