pyecharts 是基于百度开源的 ECharts 图表库封装的 Python 可视化工具，可以用极少的代码生成交互式、高颜值的网页图表，支持折线图、柱状图、饼图、地图、热力图等几十种图表类型，完美解决 matplotlib 中文乱码、静态无交互、颜值低的痛点，非常适合做数据报告、网页嵌入、数据分析展示。
本文从安装、核心概念到常用图表、配置技巧，全程配完整可运行代码 + 逐行解释，零基础也能快速上手做出专业级图表。
一、模块基础说明
1. 核心优势
- ✅ 交互性强：生成的是 HTML 网页，鼠标悬停显示数值、支持放大缩小、数据筛选、一键保存图片
- ✅ 中文友好：原生支持中文，不需要额外配置字体，完全不会乱码
- ✅ 图表丰富：支持几十种常规图表 + 地理图表，满足绝大多数可视化需求
- ✅ 语法简洁：链式调用写法，逻辑清晰，新手容易上手
2. 安装
pyecharts 是第三方库，需要手动安装，打开终端 / 命令行执行：
如果需要使用中国地图、世界地图等地理图表，还需要额外安装对应地图数据包（新手可以先装基础包，后面进阶再装）：
# 中国省级地图pip install echarts-china-provinces-pypkg# 中国市级地图pip install echarts-china-cities-pypkg# 世界地图pip install echarts-countries-pypkg
3. 核心概念（新手先了解）
- 图表类：每种图表对应一个类，比如
Line 折线图、Bar 柱状图，用什么图就导入什么类 - 配置项：所有细节设置（标题、坐标轴、图例、颜色等）都通过配置项实现，统一用
opts.xxx 调用 - 链式调用
- 渲染：生成最终的图表文件，默认生成 HTML 网页，浏览器打开就能交互查看
二、入门第一个图表：折线图（分步详解）
我们以「本周销售趋势」为例，做第一张折线图，逐行讲解每一步的作用。
完整代码
# 1. 导入需要的模块：折线图类 + 配置项模块from pyecharts.charts import Linefrom pyecharts import options as opts# 2. 创建折线图实例对象line_chart = Line()# 3. 添加X轴数据：类别、日期等横向坐标line_chart.add_xaxis(["周一", "周二", "周三", "周四", "周五", "周六", "周日"])# 4. 添加Y轴数据：第一个参数是系列名称，第二个是数值列表line_chart.add_yaxis("门店销售额", [120, 200, 150, 80, 170, 230, 190])# 5. 设置全局配置：这里只加一个标题line_chart.set_global_opts( title_opts=opts.TitleOpts(title="本周门店销售趋势"))# 6. 渲染生成HTML文件，默认生成在当前代码同目录line_chart.render("销售趋势图.html")
逐行解释
- 导入模块：
Line 是折线图的类，opts 是所有配置项的统一入口，所有标题、坐标轴、图例都从这里调用 - 创建实例
- X 轴数据：
add_xaxis() 传入一个列表，对应图表横向的所有分类 - Y 轴数据：
add_yaxis() 传入系列名称和数值列表；想加多条线，就多次调用 add_yaxis - 全局配置：
set_global_opts() 用来设置整张图的公共属性，比如标题、坐标轴、图例等 - 渲染文件：
render("文件名.html") 会生成一个网页文件，双击用浏览器打开就能看到交互式图表
运行效果
运行代码后，同级目录会出现 销售趋势图.html，打开后：
简写：链式调用写法
熟悉之后可以把所有方法连起来写，代码更紧凑，效果完全一样：
from pyecharts.charts import Linefrom pyecharts import options as opts( Line() .add_xaxis(["周一", "周二", "周三", "周四", "周五", "周六", "周日"]) .add_yaxis("门店销售额", [120, 200, 150, 80, 170, 230, 190]) .set_global_opts(title_opts=opts.TitleOpts(title="本周销售趋势")) .render("销售趋势图.html"))
三、常用基础图表（逐个示例 + 适用场景）
pyecharts 所有图表的使用逻辑完全一致：创建对象 → 加数据 → 配选项 → 渲染，只是图表类名不一样。下面是日常开发最高频的 6 种图表。
1. 柱状图 Bar
适用场景
分类对比、数量排名，是最常用的统计图表。
示例：多系列月度销售额对比
from pyecharts.charts import Barfrom pyecharts import options as optsbar = Bar()# X轴：月份bar.add_xaxis(["1月", "2月", "3月", "4月", "5月", "6月"])# 多个Y轴系列：线上、线下bar.add_yaxis("线上渠道", [100, 120, 90, 150, 130, 180])bar.add_yaxis("线下渠道", [80, 90, 110, 70, 100, 120])# 设置标题 + 坐标轴名称bar.set_global_opts( title_opts=opts.TitleOpts(title="2024上半年销售额对比"), xaxis_opts=opts.AxisOpts(name="月份"), yaxis_opts=opts.AxisOpts(name="销售额（万元）"))bar.render("柱状图.html")
解释：多次调用 add_yaxis 就可以实现多系列柱状图，每个系列会自动用不同颜色区分，右上角可以点击图例隐藏 / 显示对应系列。
2. 饼图 Pie
适用场景
展示占比、比例关系，比如各品类销售额占比、用户性别分布。
示例：商品类别销售额占比
from pyecharts.charts import Piefrom pyecharts import options as optspie = Pie()# 饼图数据格式：列表套元组，每个元组是(名称, 数值)data = [ ("电子产品", 350), ("服装鞋帽", 220), ("食品生鲜", 280), ("家居用品", 150), ("其他", 100)]pie.add("", data)# 设置标签格式：{b}是名称，{d}是百分比pie.set_series_opts(label_opts=opts.LabelOpts(formatter="{b}: {d}%"))pie.set_global_opts(title_opts=opts.TitleOpts(title="商品类别销售额占比"))pie.render("饼图.html")
常用标签占位符：
3. 散点图 Scatter
适用场景
展示两个变量的相关性、数据分布，比如身高体重分布、广告投入和销售额的关系。
示例：广告投入 vs 销售额
from pyecharts.charts import Scatterfrom pyecharts import options as optsscatter = Scatter()# X轴：广告投入（万元）scatter.add_xaxis([10, 20, 15, 30, 25, 35, 40])# Y轴：对应销售额（万元）scatter.add_yaxis("数据点", [80, 150, 110, 200, 180, 230, 260])scatter.set_global_opts( title_opts=opts.TitleOpts(title="广告投入与销售额关系"), xaxis_opts=opts.AxisOpts(name="广告投入（万元）", type_="value"), yaxis_opts=opts.AxisOpts(name="销售额（万元）"))scatter.render("散点图.html")
注意：散点图的 X 轴是数值轴，需要指定 type_="value"，默认是类目轴。
4. 折线柱状混合图（进阶）
适用场景
同时展示数量和比率，比如柱状图展示销售额，折线图展示增长率，共用 X 轴，双 Y 轴。
示例：销售额 + 增长率
from pyecharts.charts import Bar, Linefrom pyecharts import options as opts# 1. 先创建柱状图bar = Bar()bar.add_xaxis(["1月", "2月", "3月", "4月", "5月", "6月"])bar.add_yaxis("销售额", [100, 120, 90, 150, 130, 180])# 2. 创建折线图line = Line()line.add_yaxis( "同比增长率", [5, 20, -25, 66.7, -13.3, 38.5], yaxis_index=1 # 使用第二个Y轴（右侧）)# 3. 把折线图叠加到柱状图上bar.overlap(line)# 4. 配置双Y轴bar.set_global_opts( title_opts=opts.TitleOpts(title="月度销售额与增长率"), yaxis_opts=opts.AxisOpts(name="销售额（万元）"), # 第二个Y轴，在右侧 yaxis_opts2=opts.AxisOpts(name="增长率（%）", position="right"))bar.render("混合图.html")
核心方法：overlap() 可以把其他类型的图表叠加到当前图表上，实现混合图表；yaxis_index=1 表示使用第二个 Y 轴。
5. 中国地图 Map（进阶）
适用场景
展示分地区的数据，比如各省份销售额、全国用户分布。
注意：需要先安装省级地图包 pip install echarts-china-provinces-pypkg
示例：各省份销售额分布
from pyecharts.charts import Mapfrom pyecharts import options as optsmap_chart = Map()# 数据格式：(省份名称, 数值)，省份名要写标准全称data = [ ("广东省", 1200), ("北京市", 950), ("上海市", 900), ("浙江省", 850), ("江苏省", 800), ("四川省", 600), ("湖北省", 550), ("山东省", 700)]# 添加数据，指定地图类型为中国map_chart.add("销售额（万元）", data, maptype="china")# 配置视觉映射：颜色深浅对应数值大小map_chart.set_global_opts( title_opts=opts.TitleOpts(title="全国各省份销售额分布"), visualmap_opts=opts.VisualMapOpts( max_=1200, # 最大值 is_piecewise=True # 分段显示，更直观 ))map_chart.render("中国地图.html")
解释：VisualMapOpts 是视觉映射组件，可以让数值大小对应颜色深浅，一眼就能看出哪个省份数据高、哪个低。
四、核心配置项详解（常用必学）
pyecharts 的所有细节都通过配置项控制，分为全局配置项（整张图的设置）和系列配置项（单个数据系列的设置），新手掌握最常用的几个即可。
1. 全局配置项（set_global_opts）
表格
| | |
|---|
TitleOpts | | title 主标题、subtitle 副标题、pos_left 位置 |
AxisOpts | | |
LegendOpts | | |
ToolboxOpts | | is_show 是否显示，内置保存图片、数据视图等 |
VisualMapOpts | | max_最大值、is_piecewise 是否分段 |
TooltipOpts | | trigger 触发方式、formatter 格式 |
完整配置示例
bar.set_global_opts( # 标题 + 副标题 title_opts=opts.TitleOpts( title="上半年销售额", subtitle="2024年", pos_left="center" # 标题居中 ), # 显示工具箱：可以保存图片、查看数据 toolbox_opts=opts.ToolboxOpts(is_show=True), # 图例放在底部 legend_opts=opts.LegendOpts(pos_bottom="0%"), # 提示框触发方式 tooltip_opts=opts.TooltipOpts(trigger="axis"))
2. 系列配置项（set_series_opts）
针对单个数据系列的样式、标签、标记点等设置。
表格
| |
|---|
LabelOpts | |
MarkPointOpts | |
MarkLineOpts | |
示例：标记最大值、最小值、平均线
from pyecharts.charts import Linefrom pyecharts import options as optsline = Line()line.add_xaxis(["周一", "周二", "周三", "周四", "周五"])line.add_yaxis("销售额", [120, 200, 150, 80, 170])# 系列配置：标记最大最小值 + 平均线line.set_series_opts( label_opts=opts.LabelOpts(is_show=False), # 隐藏每个点的数值标签 markpoint_opts=opts.MarkPointOpts( data=[ opts.MarkPointItem(type_="max", name="最大值"), opts.MarkPointItem(type_="min", name="最小值") ] ), markline_opts=opts.MarkLineOpts( data=[opts.MarkLineItem(type_="average", name="平均值")] ))line.render("带标记的折线图.html")
五、实用进阶技巧
1. 切换主题
pyecharts 内置了多种主题，比如暗黑主题、清新主题，只需要在初始化图表时指定。
from pyecharts.charts import Barfrom pyecharts import options as optsfrom pyecharts.globals import ThemeType# 初始化时指定主题：DARK暗黑主题bar = Bar(init_opts=opts.InitOpts(theme=ThemeType.DARK, width="1000px", height="600px"))bar.add_xaxis(["1月", "2月", "3月"])bar.add_yaxis("销售额", [100, 120, 90])bar.set_global_opts(title_opts=opts.TitleOpts(title="暗黑主题图表"))bar.render("暗黑主题.html")
常用主题：LIGHT（默认浅色）、DARK（暗黑）、MACARONS（马卡龙清新）、CHALK（粉笔风格）
2. 数据区域缩放
数据量很大时，可以加数据缩放组件，拖拽查看局部数据：
bar.set_global_opts( datazoom_opts=opts.DataZoomOpts() # 底部滑动条缩放)
3. 渲染到 Jupyter Notebook
如果你用 Jupyter 做数据分析，不需要生成 HTML，直接用 render_notebook() 就能在笔记本里直接显示图表：
# 把最后一行的 render() 换成line.render_notebook()
六、新手高频易错点总结
1. 版本不兼容
pyecharts 0.x 旧版本和 1.x 新版本语法完全不同，网上很多老教程是 0.x 的写法，新手不要看。现在默认安装的都是 1.x 版本，按本文写法即可。
2. X 轴 Y 轴数据长度不一致
add_xaxis 和 add_yaxis 的列表长度必须一一对应，否则会出现数据错位、图表空白。
3. 饼图数据格式错误
饼图的数据必须是 [(名称1, 值1), (名称2, 值2)] 格式，直接传两个列表会报错。
4. 地图用不了
- 省份 / 城市名称写错，必须是标准全称，比如「广东省」不能写「广东」
5. 配置项拼写错误
所有配置项都在 opts 模块里，比如 TitleOpts 首字母大写，不要写成 titleOpts。
