引言
当下有不少主流工具可用于绘制流程框图,例如大家熟知的 Visio,或是 WPS 内置的流程图功能。近期我在撰写《机器学习高阶 <2> 项目实战》系列博客时,恰好需要用 Python 实现流程图绘制 —— 这便是我动笔写下本篇内容的契机。
在 Python 中使用 Graphviz 的核心是 “用代码定义图的节点 / 连接,调用 Graphviz 工具自动排版渲染”,步骤分为环境准备和代码使用两部分,下面详细说明。
一、先做好环境准备(必做)
Graphviz 需要 “Python 库 + 系统工具” 配合使用:
安装 Python 的 graphviz 库
打开命令提示符执行:
python -m pip install graphviz如下是使用Pycharm这个IDE在终端输入指令的图片:
2.安装系统级 Graphviz 工具
- 下载对应系统的安装包:Graphviz 官方下载页(Windows 选
win64.exe安装包)
- 安装时勾选 “Add to PATH”(或手动将安装目录的
bin文件夹(如C:\Program Files\Graphviz\bin)添加到系统环境变量Path)(如下是安装Graphviz 工具的教程)
下面的选项:
- “Do not add Graphviz to the system PATH”:不将 Graphviz 添加到系统 PATH 中
- “Add Graphviz to the system PATH for all users”:为电脑上的所有用户,将 Graphviz 添加到系统 PATH 中
- “Add Graphviz to the system PATH for current user”(当前已选中):只为当前登录的用户,将 Graphviz 添加到系统 PATH 中
复选框 “Create Graphviz Desktop Icon”:创建 Graphviz 的桌面图标
底部的 “Nullsoft Install System v3.06.1” 是这个安装程序的工具名称和版本,下方的 “上一步 (P)”“下一步 (N)”“取消 (C)” 是对应的操作按钮~
安装路径的选择:
安装成功后的界面:
- 验证:重启终端后执行
dot -V,能显示版本号则成功。
二、Python 中使用 Graphviz 的基础步骤
以 “画一个简单流程图” 为例,核心流程是:初始化图 → 添加节点 → 添加连接边 → 渲染输出。
步骤 1:初始化图
先创建一个Digraph对象(表示 “有向图”,适合流程图),可配置布局、字体等:
from graphviz import Digraph # 初始化有向图,设置布局方向(TB=从上到下)、中文支持 dot = Digraph( graph_attr={"rankdir": "TB", "fontname": "SimHei"}, # TB=从上到下布局,SimHei支持中文 node_attr={"shape": "rect", "style": "filled", "fillcolor": "#f0f8ff"} # 节点样式:矩形、浅蓝色填充 )步骤 2:添加节点
用dot.node("节点ID", "节点显示文本")添加节点(ID 是代码中区分节点的标识,文本是图中显示的内容):
# 添加节点:ID分别为start、step1、step2、end dot.node("start", "开始") dot.node("step1", "执行任务A") dot.node("step2", "执行任务B") dot.node("end", "结束")步骤 3:添加连接边
用dot.edge("起点ID", "终点ID")定义节点之间的连接:
# 连接节点:start → step1 → step2 → end dot.edge("start", "step1") dot.edge("step1", "step2") dot.edge("step2", "end")步骤 4:渲染输出
用render()生成图片文件(支持 PNG、PDF 等格式),view=True会自动打开图片:
# 生成PNG图片,文件名为"simple_flow" dot.render("simple_flow", format="png", view=True) print("流程图已生成:simple_flow.png")三、进阶:自定义样式(可选)
可以调整节点颜色、边的样式、添加标签等,比如:
from graphviz import Digraph dot = Digraph(graph_attr={"rankdir": "TB", "fontname": "SimHei"}) # 自定义节点样式 dot.node("a", "重要节点", fillcolor="#ffcccc", style="filled") # 红色填充 dot.node("b", "普通节点", fillcolor="#f0f8ff", style="filled") # 自定义边:加标签、虚线样式 dot.edge("a", "b", label="依赖关系", style="dashed", color="#666666") dot.render("custom_style", format="png", view=True)常用场景示例
除了流程图,还可以画树形结构、依赖图等,比如画一个二叉树:
from graphviz import Digraph dot = Digraph(graph_attr={"rankdir": "TB", "fontname": "SimHei"}) dot.node("root", "根节点") dot.node("left", "左子节点") dot.node("right", "右子节点") dot.edge("root", "left") dot.edge("root", "right") dot.render("binary_tree", format="png", view=True)四、项目实战
这段代码是一个Graphviz 环境诊断工具,专门用于在 Windows 系统中自动检测 Graphviz 的安装、配置及可用性问题,解决用户在使用 Python 调用 Graphviz 时常见的报错(如找不到 dot.exe、环境变量未配置、Python 库未安装等)。它不仅能定位问题,还会给出明确的修复提示,并通过实际测试验证 Graphviz 是否能正常工作。
# 诊断脚本:diagnose.py import os import sys import subprocess def check_python_version(): print(f"Python 版本: {sys.version}") print() def check_graphviz_installation(): print("检查 Graphviz 安装...") # 检查常见安装路径 possible_paths = [ r"C:\Program Files\Graphviz\bin", r"C:\Program Files (x86)\Graphviz\bin", r"C:\Graphviz\bin", ] found = False for path in possible_paths: dot_exe = os.path.join(path, "dot.exe") if os.path.exists(dot_exe): print(f"✓ 找到 Graphviz: {path}") found = True # 测试版本 try: result = subprocess.run([dot_exe, "-V"], capture_output=True, text=True, timeout=5) if result.returncode == 0: print(f" Graphviz 版本: {result.stdout.strip()}") else: print(f" ✗ 无法获取版本信息") except: print(f" ✗ 无法执行 dot 命令") if not found: print("✗ 未找到 Graphviz") print() print("请安装 Graphviz:") print("1. 访问 https://graphviz.org/download/") print("2. 下载 Windows 版本") print("3. 安装时务必勾选 'Add Graphviz to the system PATH for all users'") return found def check_python_packages(): print("\n检查 Python 包...") packages = ["graphviz"] for package in packages: try: if package == "graphviz": import graphviz version = graphviz.__version__ if hasattr(graphviz, '__version__') else "未知" print(f"✓ {package}: {version}") else: __import__(package) print(f"✓ {package}: 已安装") except ImportError: print(f"✗ {package}: 未安装") if package == "graphviz": print(" 运行: pip install graphviz") def check_path_environment(): print("\n检查 PATH 环境变量...") path = os.environ.get("PATH", "") path_dirs = path.split(os.pathsep) graphviz_found = False for dir_path in path_dirs: if "graphviz" in dir_path.lower() and os.path.exists(os.path.join(dir_path, "dot.exe")): print(f"✓ Graphviz 在 PATH 中: {dir_path}") graphviz_found = True if not graphviz_found: print("✗ Graphviz 不在 PATH 中") return graphviz_found def run_simple_test(): print("\n运行简单测试...") # 创建最简单的图表 dot_source = """ digraph G { A -> B; A -> C; B -> D; C -> D; } """ # 保存为 .dot 文件 with open("test_graph.dot", "w") as f: f.write(dot_source) print("✓ 已创建测试文件: test_graph.dot") # 尝试使用 dot 命令转换 try: result = subprocess.run( ["dot", "-Tpng", "-otest_graph.png", "test_graph.dot"], capture_output=True, text=True, timeout=10 ) if result.returncode == 0: print("✓ 成功生成 test_graph.png") if os.path.exists("test_graph.png"): print(f" 文件大小: {os.path.getsize('test_graph.png')} 字节") return True else: print(f"✗ 生成失败: {result.stderr}") return False except FileNotFoundError: print("✗ 找不到 dot 命令") return False except Exception as e: print(f"✗ 测试失败: {e}") return False if __name__ == "__main__": print("=" * 60) print("Graphviz 诊断工具") print("=" * 60) check_python_version() path_ok = check_path_environment() install_ok = check_graphviz_installation() check_python_packages() if install_ok: test_ok = run_simple_test() if test_ok: print("\n" + "=" * 60) print("✓ 所有检查通过!") print("=" * 60) else: print("\n" + "=" * 60) print("✗ 测试失败,请检查 Graphviz 安装") print("=" * 60) else: print("\n" + "=" * 60) print("✗ 请先安装 Graphviz") print("=" * 60)代码采用模块化设计,将诊断逻辑拆分为多个独立函数,按“基础环境→配置检查→软件安装→依赖库→实际功能测试”的故障排查逻辑逐步执行,既符合开发者排查问题的思维习惯,也让代码结构清晰、易维护。
功能模块拆分(每个函数负责单一诊断任务)
| 函数名 | 核心功能 |
|---|---|
check_python_version | 打印当前 Python 版本,排查 Python 版本兼容性问题(基础环境检查) |
check_path_environment | 检查系统PATH环境变量中是否包含 Graphviz 的bin目录(关键配置检查) |
check_graphviz_installation | 遍历 Windows 系统中 Graphviz 的常见安装路径,检测是否安装了 Graphviz,并尝试获取版本信息 |
check_python_packages | 检查 Python 的graphviz库是否安装及版本(依赖库检查) |
run_simple_test | 创建简单的 dot 文件,调用dot命令生成 PNG 图片,验证 Graphviz 实际功能是否可用 |
关键设计细节
- 自动化路径检测:
check_graphviz_installation函数预设了 Windows 系统中 Graphviz 的常见安装路径(如C:\Program Files\Graphviz\bin),无需用户手动指定,提升易用性。 - 友好的用户反馈:使用
✓/✗符号直观显示检查结果,失败时给出具体的解决步骤(如 Graphviz 下载地址、安装时勾选 PATH 的提示),新手能直接参考。 - 异常处理与健壮性:在执行
subprocess调用(如dot -V、生成图片)时加入异常捕获,避免脚本因个别错误崩溃,确保诊断流程能完整执行。 - 实际功能验证:不只是停留在 “配置检查” 层面,
run_simple_test函数会创建测试文件并尝试生成图片,确保 Graphviz 能真正工作,而非仅表面配置正确。 - 执行逻辑串联:在主程序中按顺序执行所有诊断函数,先检查基础环境,再验证实际功能,最后根据检查结果给出最终结论(如 “所有检查通过” 或 “请先安装 Graphviz”)。
控制台的结果:
运行结果:
五、常见的错误解决方式:
选择 “Add Graphviz to the system PATH for current user” 本身是没问题的,但直接去 PyCharm 运行代码大概率会仍报错—— 核心原因是:PyCharm 启动时会读取当时的系统环境变量,而你是安装 Graphviz 后才添加的 PATH,已打开的 PyCharm 还没加载到新的环境变量。
解决办法很简单:
- 先完全关闭 PyCharm(包括后台进程);
- 重新打开 PyCharm,再运行代码。
如下PyCharm 里检查环境变量是否已经包含了 Graphviz 的路径:
方法 1:用代码直接打印系统 PATH(最直观)
你可以在 PyCharm 里新建一个临时 Python 文件,运行以下代码,直接查看系统 PATH 中是否包含 Graphviz 的bin目录(比如C:\Program Files\Graphviz\bin):
import os # 获取系统的PATH环境变量 system_path = os.environ.get("PATH", "") # 按分号分割PATH里的所有路径 path_list = system_path.split(";") # 打印所有路径,或筛选包含"Graphviz"的路径 print("系统PATH中包含的路径:") for path in path_list: if "Graphviz" in path: # 筛选Graphviz相关路径 print(f"找到Graphviz路径:{path}")如果运行后输出了类似“找到Graphviz路径:C:\Program Files\Graphviz\bin”的内容,说明 PATH 已包含;如果没有输出,说明环境变量还没加载到 PyCharm 中(需要重启 PyCharm)
方法 2:通过 PyCharm 的 “运行配置” 查看环境变量
步骤如下:
- 打开 PyCharm,点击顶部菜单栏的Run(运行)→ Edit Configurations(编辑配置);
- 在弹出的窗口中,选择你当前运行代码对应的配置(比如 Python 脚本的配置);
- 找到右侧的Environment variables(环境变量)选项,点击它旁边的文件夹图标(或 “...” 按钮);
- 在新窗口中,找到
PATH变量,点击展开它的内容,查看列表中是否包含 Graphviz 的bin目录。
补充说明
如果检查后发现 PATH 里没有 Graphviz 路径,只需完全关闭 PyCharm(包括后台进程)再重新打开,PyCharm 会重新加载系统环境变量,此时再检查就能看到了。