Python之graphviz-python包语法、参数和实际应用案例

Python Graphviz 完整使用指南

graphviz 是 Python 封装 Graphviz 绘图引擎 的第三方库，专门用于绘制流程图、有向图、无向图、树形图、架构图、拓扑图等图形，底层依赖官方 Graphviz 二进制程序，是代码可视化、算法流程、系统架构、数据结构可视化的主流工具。

一、核心功能介绍

1. 基础功能

2. 适用场景

算法流程图、软件架构图、网络拓扑图、决策树、状态机、类继承图、调用关系图、思维导图等。

二、环境安装（两步必做）

关键：Python 库 + 系统 Graphviz 程序 都要装，缺一不可。

步骤1：安装 Python 第三方包

pip install graphviz

步骤2：安装系统 Graphviz 二进制程序

graphviz Python 包只是调用接口，真正绘图依赖官方引擎：

验证安装

import graphviz
print(graphviz.__version__)

无报错即 Python 包安装成功；执行下方基础代码能弹出图片，说明系统环境正常。

三、核心语法、类、参数详解

1. 两大核心类

2. 构造函数通用参数

graphviz.Digraph(
name='图名称', # 图形内部标识名
comment='注释', # 源码注释
format='png', # 输出格式：png/svg/pdf/jpg/gif/dot
engine='dot', # 布局引擎
encoding='utf-8', # 编码，中文必备
directory='./output' # 文件保存目录
)

常用布局引擎 engine（重点）

3. 核心方法（增节点、增连线、渲染）

（1）node() 添加单个节点

g.node(name, label=None, **attrs)

• name：节点唯一标识（字符串，不可重复）
• label：节点显示文字（支持中文、换行 \\n）
• 节点样式属性（attrs）
  • shape：形状 box(方框)、ellipse(椭圆，默认)、circle、diamond(菱形)、record(表格节点)
  • color：边框颜色
  • fillcolor：填充色，配合 style='filled' 使用
  • style：filled(填充)、dashed(虚线边框)、bold(粗边框)
  • fontname：字体（中文推荐 SimHei 黑体、Microsoft YaHei 微软雅黑）
  • fontsize：字体大小

（2）edge() / edges() 添加连线

# 单条连线
g.edge(起点节点名, 终点节点名, label="连线文字", **attrs)

# 批量多条连线
g.edges([(A,B), (B,C), (B,D)])

• 连线样式属性
  • label：连线上的文字
  • color：线条颜色
  • style：dashed(虚线)、dotted(点线)、bold(粗线)
  • arrowhead：箭头样式，none 取消箭头
  • dir：控制箭头方向

（3）subgraph 子图/集群

• 普通子图：分组节点，无外框
• 集群 cluster：名称必须以 cluster_ 开头，自动带外框分组，视觉分区。

（4）渲染与输出方法

# 1. 渲染并保存文件 + 自动打开预览（常用）
g.render(filename='文件名', view=True)

# 2. 仅生成 DOT 源码字符串
print(g.source)

# 3. 直接查看图片（Jupyter 专属）
g.view()

4. 全局样式（统一设置）

# 全局节点默认样式
g.attr('node', shape='box', style='filled', fillcolor='lightblue')

# 全局连线默认样式
g.attr('edge', color='gray', style='solid')

# 全局图形整体样式
g.attr(rankdir='LR') # LR=从左到右；TB=从上到下(默认)

• rankdir='LR'：流程图横向排布，高频使用。

5. 中文乱码解决方案（必看）

四、8 个实战应用案例（可直接运行）

所有案例默认解决中文乱码，环境正常即可运行。

案例1：基础有向流程图（最简单入门）

场景：普通业务流程、步骤流转。

from graphviz import Digraph

# 创建有向图，格式png，编码utf8
dot = Digraph(format='png', encoding='utf-8')
# 全局字体
dot.attr('node', fontname='SimHei')

# 添加节点
dot.node('A', '开始')
dot.node('B', '数据采集')
dot.node('C', '数据处理')
dot.node('D', '结果输出')
dot.node('E', '结束')

# 添加连线
dot.edges([('A','B'), ('B','C'), ('C','D'), ('D','E')])

# 渲染并打开
dot.render('01_基础流程图', view=True)

案例2：带分支判断的决策流程图

场景：if-else 分支、判断逻辑、审批流程。

from graphviz import Digraph

dot = Digraph(format='png', encoding='utf-8')
dot.attr('node', fontname='SimHei')

dot.node('start', '提交申请', shape='box')
dot.node('judge', '条件判断', shape='diamond')
dot.node('yes', '审核通过')
dot.node('no', '审核驳回')
dot.node('end1', '执行流程')
dot.node('end2', '重新提交')

# 带标签连线
dot.edge('start', 'judge')
dot.edge('judge', 'yes', label='通过')
dot.edge('judge', 'no', label='不通过')
dot.edge('yes', 'end1')
dot.edge('no', 'end2')

dot.render('02_分支决策图', view=True)

案例3：无向图（网络/关系图）

场景：好友关系、设备互联、无方向拓扑。

from graphviz import Graph

g = Graph(format='png', encoding='utf-8')
g.attr('node', fontname='SimHei', shape='circle')

g.edges([
('设备1', '设备2'),
('设备1', '设备3'),
('设备2', '设备3'),
('设备3', '设备4')
])

g.render('03_无向关系图', view=True)

案例4：树形结构（目录树/决策树/组织架构）

场景：文件目录、层级架构、二叉树。

from graphviz import Digraph

dot = Digraph(format='png', encoding='utf-8')
dot.attr('node', fontname='SimHei', shape='box')
dot.attr(rankdir='TB') # 自上而下

dot.node('root', '根目录')
dot.edges([
('root', '文件夹A'),
('root', '文件夹B'),
('文件夹A', '文件1'),
('文件夹A', '文件2'),
('文件夹B', '文件3')
])

dot.render('04_树形目录图', view=True)

案例5：集群子图（分区架构图）

场景：系统模块分区、微服务分组、前后端分离架构。
cluster_ 前缀自动生成带框分组。

from graphviz import Digraph

dot = Digraph(format='png', encoding='utf-8')
dot.attr('node', fontname='SimHei')

# 集群1：前端服务
with dot.subgraph(name='cluster_front') as c1:
c1.attr(label='前端模块')
c1.node('web1', '网页端')
c1.node('app1', 'APP端')

# 集群2：后端服务
with dot.subgraph(name='cluster_back') as c2:
c2.attr(label='后端服务')
c2.node('api', '接口服务')
c2.node('db', '数据库')

# 跨集群连线
dot.edge('web1', 'api', label='请求')
dot.edge('app1', 'api')
dot.edge('api', 'db', label='读写数据')

dot.render('05_集群架构图', view=True)

案例6：状态机图（状态流转）

场景：设备状态、订单状态、有限状态机。

from graphviz import Digraph

dot = Digraph(format='png', encoding='utf-8')
dot.attr('node', fontname='SimHei', shape='ellipse')

dot.node('init', '初始状态')
dot.node('run', '运行中')
dot.node('pause', '暂停')
dot.node('stop', '停止')

# 双向/多状态跳转
dot.edge('init', 'run', label='启动')
dot.edge('run', 'pause', label='暂停')
dot.edge('pause', 'run', label='恢复')
dot.edge('run', 'stop', label='终止')
dot.edge('pause', 'stop', label='强制停止')

dot.render('06_状态机图', view=True)

案例7：自定义样式（颜色、虚线、填充）

场景：美化图表、区分重要节点/线路。

from graphviz import Digraph

dot = Digraph(format='png', encoding='utf-8')
dot.attr('node', fontname='SimHei')

# 普通节点
dot.node('A', '正常节点', style='filled', fillcolor='white')
# 高亮节点
dot.node('B', '重要节点', style='filled', fillcolor='red', fontcolor='white')
# 警告节点
dot.node('C', '警告节点', style='filled', fillcolor='yellow')

# 实线 + 虚线连线
dot.edge('A', 'B', color='blue')
dot.edge('B', 'C', style='dashed', color='orange')

dot.render('07_样式美化图', view=True)

案例8：动态批量绘图（Python 循环生成）

场景：动态数据、自动生成大量节点/连线（日志分析、调用链）。

from graphviz import Digraph

dot = Digraph(format='png', encoding='utf-8')
dot.attr('node', fontname='SimHei', shape='circle')

# 模拟动态数据
nodes = [f'节点{i}' for i in range(1, 6)]
# 循环添加节点
for n in nodes:
dot.node(n)

# 循环添加连线
for i in range(len(nodes)–1):
dot.edge(nodes[i], nodes[i+1], label=f'链路{i+1}')

dot.render('08_动态批量图', view=True)

五、常见错误 & 解决方案

错误1：ExecutableNotFound: failed to execute ['dot', …]

原因：系统未安装 Graphviz 程序 / 未配置环境变量。
解决：

错误2：中文显示方框/乱码

原因：未指定中文字体、编码错误。
解决：

错误3：节点名称重复报错

原因：node(name) 的第一个参数是唯一ID，不能重名，label 才是显示文字。
解决：ID 保证唯一，重复文字放 label。

错误4：图片无法打开、文件生成失败

原因：文件名含特殊字符、路径中文、权限不足。
解决：文件名只用英文/数字，保存路径不要有中文。

错误5：连线重叠、布局混乱

原因：节点过多、布局引擎不合适。
解决：

错误6：Jupyter 中不自动弹窗

解决：直接输出对象即可渲染：

dot # Jupyter 单元格最后一行写对象名

六、使用注意事项

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。