5分钟上手PyGWalker：从Jupyter到Streamlit的全场景可视化方案

你是否还在为不同数据科学环境下的可视化工具切换而烦恼？PyGWalker（Python Graphic Walker）作为一款开源数据可视化工具，提供了跨平台、低代码的解决方案，让你在Jupyter、Streamlit、Gradio等主流环境中轻松实现数据探索与图表生成。本文将通过实战案例，带你掌握PyGWalker在各类开发环境中的快速部署与核心功能应用。

环境准备与基础安装

PyGWalker支持Python 3.6+环境，通过pip即可完成安装：

pip install pygwalker

项目核心API定义在pygwalker/api/pygwalker.py，主要包含walk()、render()和table()三个核心函数，分别用于交互式探索、图表渲染和数据表格展示。

Jupyter生态系统集成

Jupyter Notebook/JupyterLab作为数据科学家的首选开发环境，PyGWalker提供了深度集成方案。

基础使用示例

import pygwalker as pyg
import pandas as pd

# 加载示例数据集
df = pd.read_csv("https://kanaries-app.s3.ap-northeast-1.amazonaws.com/public-datasets/bike_sharing_dc.csv")

# 初始化可视化探索界面
walker = pyg.walk(df, spec="./gw_config.json")

上述代码来自examples/jupyter_demo.ipynb，通过walk()函数创建的交互式界面支持：

• 拖拽字段生成图表
• 切换数据视图与可视化视图
• 保存图表配置到本地JSON文件

高级功能

Jupyter环境中还提供了专用渲染函数：

# 仅渲染图表（基于保存的配置）
pyg.render(df, spec="./gw_config.json")

# 仅展示数据表格
pyg.table(df)

核心实现逻辑位于pygwalker/api/jupyter.py，通过env参数自动适配Jupyter Widget或HTML展示模式。

Streamlit应用开发

Streamlit作为快速构建数据应用的框架，PyGWalker提供了专门的组件化支持。

完整应用示例

from pygwalker.api.streamlit import StreamlitRenderer
import pandas as pd
import streamlit as st

# 设置页面配置
st.set_page_config(page_title="PyGWalker Streamlit Demo", layout="wide")

# 缓存PyGWalker渲染器
@st.cache_resource
def get_pyg_renderer() -> "StreamlitRenderer":
    df = pd.read_csv("https://kanaries-app.s3.ap-northeast-1.amazonaws.com/public-datasets/bike_sharing_dc.csv")
    return StreamlitRenderer(df, spec="./gw_config.json")

renderer = get_pyg_renderer()

# 创建多标签界面
tab1, tab2, tab3 = st.tabs(["探索界面", "数据概览", "图表展示"])
with tab1:
    renderer.explorer()
with tab2:
    renderer.explorer(default_tab="data")
with tab3:
    renderer.chart(0)  # 渲染第1个图表
    renderer.chart(1)  # 渲染第2个图表

代码来自examples/streamlit_demo.py，关键实现基于pygwalker/api/streamlit.py中的StreamlitRenderer类，支持：

• 组件化渲染（explorer()/viewer()/chart()）
• 缓存机制避免重复计算
• Streamlit主题自动适配

Gradio交互式应用

Gradio作为另一种流行的Web应用构建工具，PyGWalker提供了简洁的集成方案：

import gradio as gr
import pandas as pd
from pygwalker.api.gradio import get_html_on_gradio

def load_data(file):
    df = pd.read_csv(file.name)
    return get_html_on_gradio(df, spec="./gw_config.json")

with gr.Blocks() as demo:
    file = gr.File(label="上传CSV文件")
    html_output = gr.HTML(label="PyGWalker可视化界面")
    file.change(load_data, inputs=file, outputs=html_output)

demo.launch()

上述代码通过get_html_on_gradio()函数（定义于pygwalker/api/gradio.py）将可视化界面嵌入Gradio应用，实现文件上传与动态可视化联动。

其他环境支持

Marimo笔记本

Marimo作为新兴的交互式笔记本，PyGWalker提供了专用API：

import marimo as mo
import pandas as pd
from pygwalker.api.marimo import walk

app = mo.App()

@app.cell
def load_data():
    df = pd.read_csv("https://kanaries-app.s3.ap-northeast-1.amazonaws.com/public-datasets/bike_sharing_dc.csv")
    walk(df)  # 直接在Marimo中渲染

if __name__ == "__main__":
    app.run()

代码示例来自examples/marimo_demo.py，通过walk()函数直接在Marimo界面中嵌入交互式可视化面板。

Kaggle环境适配

PyGWalker针对Kaggle环境做了专门优化，自动调整字体大小和渲染模式，相关代码位于pygwalker/api/jupyter.py：

if check_kaggle():
    auto_set_kanaries_api_key_on_kaggle()
if get_kaggle_run_type() == "batch":
    adjust_kaggle_default_font_size()
    env = "JupyterPreview"  # 切换为适合Kaggle的预览模式

核心功能与最佳实践

图表配置保存与加载

PyGWalker支持将图表配置保存为JSON文件，通过spec参数实现复用：

# 保存配置
walker = pyg.walk(df, spec="./gw_config.json")  # 自动保存到文件

# 加载配置
walker = pyg.walk(df, spec="./saved_config.json")

配置文件格式定义在pygwalker/services/spec.py，支持手动编辑或通过UI界面调整后导出。

主题与外观定制

通过theme_key和appearance参数定制界面风格：

# 使用streamlit主题，自动匹配浅色/深色模式
pyg.walk(df, theme_key="streamlit", appearance="media")

支持的主题包括"vega"、"g2"和"streamlit"，定义于pygwalker/_typing.py中的IThemeKey类型。

项目资源与社区支持

• 官方文档：docs/README.zh.md
• 示例代码库：examples/
• 问题反馈：项目GitHub Issues
• 开发指南：docs/CONTRIBUTING.md

PyGWalker作为开源项目，持续欢迎社区贡献代码、文档或使用反馈，共同完善这一数据可视化工具。

通过本文介绍的方法，你可以在不同数据科学环境中快速部署PyGWalker，实现低代码数据可视化与探索分析。无论是Jupyter中的交互式分析，还是Streamlit/Gradio构建的Web应用，PyGWalker都能提供一致且高效的可视化体验，帮助你更专注于数据洞察而非工具配置。