企业官网建设流程全解析

PyGWalker 快速上手指南：在 Jupyter Notebook 中用拖拽式交互 UI 完成探索性数据分析

【免费下载链接】pygwalkerPyGWalker: Turn your dataframe into an interactive UI for visual analysis项目地址: https://gitcode.com/GitHub_Trending/py/pygwalker

PyGWalker 是一个将 pandas / polars DataFrame 转换为 Tableau 风格交互式可视化界面的 Python 库，让你在 Jupyter Notebook 中通过简单的拖拽操作完成数据探索、清洗与可视化。本文基于仓库中的官方文档 docs/README.fr.md（法语版）与 README.md，并结合仓库源码，完整讲解安装配置、pyg.walk()核心参数、计算引擎选型、隐私策略命令与图表导出 API，读完即可在本地或云端 Notebook 中直接上手。

PyGWalker 是什么：Py 与 Graphic Walker 的结合

PyGWalker 读作 “Pig Walker”，其名称是 "Python binding ofGraphicWalker" 的缩写。它将 Jupyter Notebook（以及其它基于 Jupyter 的笔记本环境）与 Graphic Walker——一款开源的 Tableau 替代方案——集成在一起，让数据科学家通过简单的拖拽操作即可分析数据、观察数据模式，无需编写绘图代码。

从当前仓库源码看，其顶层 API 均定义在 pygwalker/api/adapter.py 中：walk、render、table三个入口会根据运行环境自动分流到 Jupyter 通道（pygwalker/api/jupyter.py）或 Web 服务器通道（pygwalker/api/webserver.py），而 pygwalker/init.py 对外导出walk、render、table、to_html、FieldSpec、GlobalVarManager、component、Walker与spec模块。仓库当前版本为0.6.0rc0（见 pygwalker/init.py）。

安装 PyGWalker

在命令行中使用 pip 或 conda 安装：

pip 安装

pip install pygwalker

若想尝鲜体验最新功能，可以升级到最新发布版，甚至获取包含最新特性与 bug 修复的预发布版本：

pip install pygwalker --upgrade pip install pygwalker --upgrade --pre

Conda-forge 安装

conda install -c conda-forge pygwalker

或使用 mamba：

mamba install -c conda-forge pygwalker

说明：PyGWalker 0.6 系列经过验证支持的 Python 版本为 3.10、3.11、3.12 与 3.13，前端与发布工作流使用 Node.js 22.x 构建（见 docs/RELEASE_0_6.md）。

在 Jupyter Notebook 中使用 PyGWalker

快速开始

在 Jupyter Notebook 中导入 pygwalker 与 pandas：

import pandas as pd import pygwalker as pyg

PyGWalker 不会打断你现有的工作流。例如，用如下方式加载 DataFrame 后即可唤起 Graphic Walker 界面：

df = pd.read_csv('./bike_sharing_dc.csv') walker = pyg.walk(df)

这就完成了。现在你拥有一个 Tableau 风格的交互式 UI，可以通过拖拽变量完成数据分析和可视化。

最佳实践：状态持久化与大数据集计算

df = pd.read_csv('./bike_sharing_dc.csv') walker = pyg.walk( df, spec="./chart_meta_0.json", # 该 JSON 文件用于保存图表状态；完成一个图表后需点击界面中的保存按钮（未来会支持 autosave） kernel_computation=True, # 设为 True 时，pygwalker 使用 DuckDB 作为计算引擎，可探索更大的数据集（<=100GB） )

在 0.6 版本线上，官方更推荐用spec_path与新的computation参数表达同样的意图（见 docs/RELEASE_0_6.md）：

df = pd.read_csv('./bike_sharing_dc.csv') walker = pyg.walk( df, spec_path="./chart_meta_0.json", # 本地文件，用于加载与保存图表状态 computation="kernel", # 在 Python 内核中使用 DuckDB，以支撑更大的数据集 )

离线与在线示例

• 离线 Notebook 代码示例可参考 pygwalker-offline-example 仓库，以及 HTML 版 Notebook 预览；
• 在线示例包括 Kaggle 上的 Airbnb EDA 演示与 Google Colab 在线运行环境。

核心参数详解：spec 与 computation

图表配置参数：spec与spec_path

根据 README.md 中的说明，图表配置相关参数包括：

• spec_path：本地文件路径，用于保存/加载图表配置；
• spec：图表配置对象，可以是 JSON 字符串、配置 ID 或远程 URL。

在 pygwalker/utils/spec.py 的resolve_spec_input()中可以看到二者的解析规则：当spec_path为None时保留spec的旧行为（若spec是路径类对象则取其文件路径）；当同时传入非空的spec与spec_path时会抛出ValueError，要求只传其一，并建议本地配置文件统一走spec_path。spec参数的输入类型判定在 pygwalker/spec.py 的migrate()中也有体现：既可以是 dict / list 对象，也可以是合法 JSON 字符串或已存在的本地文件路径。

计算引擎参数：computation与遗留参数

PyGWalker 0.6 引入了新的统一计算模型computation，可选值：

• "auto"（默认）：自动选择计算后端；
• "browser"：仅前端计算；
• "kernel"：本地基于 DuckDB 的 Python 内核计算；
• "cloud"：Kanaries 云端计算。

同时保留的遗留布尔参数及废弃时间线如下（均计划在 PyGWalker 0.7.0 中移除）：

• kernel_computation：遗留布尔值，表示使用 DuckDB 作为计算引擎，建议改用computation="kernel"或computation="browser"；
• cloud_computation：遗留布尔值，表示使用 Kanaries 云端计算，建议改用computation="cloud"；
• use_kernel_calc：内核计算的废弃别名，建议改用computation="kernel"或computation="browser"。

源码层面的解析逻辑位于 pygwalker/utils/computation.py 的resolve_computation_mode()：若显式传入非auto的computation值同时又启用了上述遗留参数，会直接抛出ValueError要求二选一；"browser"映射为(False, False)，"kernel"映射为(True, False)，"cloud"映射为(False, True)。值得注意的推断逻辑是：当数据集是数据库连接器（Connector或str）且未显式指定计算模式时，会强制启用内核计算（force_kernel_for_connectors=True），保证连接器场景下的查询可执行。

pyg.walk()完整参数参考

根据 README.md 的 API 参考表与 pygwalker/api/adapter.py 中的函数签名，pyg.walk()主要参数如下：

可复用 Walker 对象与静态导出

对于需要在多个环境中渲染同一份数据的场景，0.6 版本推荐优先使用可复用的Walker对象，并自行选择渲染方式（见 pygwalker/api/walker.py）：

walker = pyg.Walker(df, spec_path="./chart_meta_0.json", computation="browser") walker.show() # 自动检测 Notebook 或脚本模式 html = walker.to_html() html = pyg.to_html(walker)

从源码看，Walker.show()会解析env参数并路由到jupyter-anywidget（默认、首选渲染通道）、jupyter-convert、jupyter-preview或webserver模式；Walker.to_html()与to_html_without_iframe()会先检查kernel_computation与cloud_computation，若处于实时计算模式则抛出ValueError，因为静态 HTML 只支持浏览器计算。Walker.to_streamlit()则会把构造参数透传给StreamlitRenderer，实现同一 Walker 的多端复用。

在 UI 中完成探索后，还可以把当前图表状态导出为可复现的 Python 代码（实现于 pygwalker/api/pygwalker.py 的PygWalker.to_code()，它会序列化当前 spec 并生成pyg.walk(df, spec=...)代码）：

code = walker.to_code(dataset_name="df") print(code)

如果你持有旧版本保存的 spec，可以在提交前将其迁移到当前 schema：

migrated_spec = pyg.spec.migrate(open("./old_chart_meta.json").read())

pyg.spec.migrate()的实现位于 pygwalker/spec.py，它支持 dict / list / JSON 字符串 / 本地文件路径四种输入，迁移后会自动补充version、chart_map与workflow_list字段。

图表的程序化导出

在 UI 中保存图表后，可以直接从 Python 中获取图表图片：

walker = pyg.walk(df, spec_path="./chart_meta_0.json") # 在 UI 中编辑图表并点击保存按钮 walker.save_chart_to_file("Chart 1", "chart1.svg", save_type="svg") png_bytes = walker.export_chart_png("Chart 1") svg_bytes = walker.export_chart_svg("Chart 1")

对应的 API 定义在 pygwalker/api/pygwalker.py：save_chart_to_file(chart_name, path, save_type)支持"html"、"png"、"svg"三种格式；export_chart_html/export_chart_png/export_chart_svg分别返回 HTML 字符串或 PNG/SVG 字节流；chart_list属性可获取已保存图表的名称列表。这些方法最终通过ChartExportManager（pygwalker/services/chart_export.py）实现。

已测试的运行环境

根据 docs/README.fr.md 与 README.md 的环境矩阵：

• Jupyter Notebook
• Google Colab
• Kaggle Code
• Jupyter Lab（法语版标注为“进行中：仍有少量 CSS 小问题”）
• Jupyter Lite
• Databricks Notebook（自0.1.4a0起）
• Visual Studio Code 的 Jupyter 扩展（自0.1.4a0起）
• 大多数兼容 IPython 内核的 Web 应用（自0.1.4a0起）
• Streamlit（自0.1.4.9起），通过pygwalker.api.streamlit.StreamlitRenderer启用
• DataCamp Workspace（自0.1.4a0起）

法语版文档还列出 Hex Projects（自0.1.4a0起）为已验证环境，英文版 README 则将其标记为待验证，并额外列出 Panel（通过 panel-graphic-walker）与 marimo（自0.4.9.11起）。其余环境欢迎通过提交 issue 补充。

在 Streamlit 中使用

Streamlit 让你无需关心 Web 应用实现细节即可托管 pygwalker 的 Web 版本。参考 examples/streamlit_demo.py 与如下模式：

from pygwalker.api.streamlit import StreamlitRenderer import pandas as pd import streamlit as st # 调整 Streamlit 页面宽度 st.set_page_config( page_title="Use Pygwalker In Streamlit", layout="wide" ) # 添加标题 st.title("Use Pygwalker In Streamlit") # 建议缓存 renderer，避免内存爆炸 @st.cache_resource def get_pyg_renderer() -> "StreamlitRenderer": df = pd.read_csv("./bike_sharing_dc.csv") # 若想使用保存图表配置的功能，设置 spec_io_mode="rw" return StreamlitRenderer(df, spec_path="./gw_config.json", spec_io_mode="rw") renderer = get_pyg_renderer() renderer.explorer()

若已创建可复用的Walker，Streamlit 可以直接渲染它：

import pygwalker as pyg from pygwalker.api.streamlit import StreamlitRenderer walker = pyg.Walker(df, spec_path="./gw_config.json", computation="kernel") renderer = StreamlitRenderer(walker) renderer.explorer()

隐私配置与数据安全（pygwalker >= 0.3.10）

PyGWalker 提供pygwalker config命令行工具来设置隐私策略：

$ pygwalker config --help usage: pygwalker config [-h] [--set [key=value ...]] [--reset [key ...]] [--reset-all] [--list] Modify configuration file. (default: ~/Library/Application Support/pygwalker/config.json) Available configurations: - privacy ['offline', 'update-only', 'events'] (default: update-only). "offline": 完全离线，不发送任何数据，不请求任何 API "update-only": 仅检查 pygwalker 是否有新版本可更新 "events": 共享 pygwalker 中使用了哪些功能的事件数据，仅包含你到达了哪些功能的事件数据，用于产品优化。不会发送你分析的数据。 - kanaries_token ['your kanaries token'] (default: empty string). 你的 kanaries token，可以从 kanaries.net 获取。 通过 kanaries token，你可以在 pygwalker 中使用 kanaries 服务，例如分享图表、分享配置。 options: -h, --help show this help message and exit --set [key=value ...] Set configuration. e.g. "pygwalker config --set privacy=update-only" --reset [key ...] Reset user configuration and use default values instead. e.g. "pygwalker config --reset privacy" --reset-all Reset all user configuration and use default values instead. e.g. "pygwalker config --reset-all" --list List current used configuration.

源码层面，pygwalker/services/config.py 定义了默认配置{"privacy": "update-only", "kanaries_token": ""}，配置文件存放于用户配置目录（appdirs.user_config_dir("pygwalker")）下的config.json，并提供set_config、reset_config、reset_all_config、get_config等读写函数。要点：

• privacy三种模式：offline完全离线，不发送任何数据也不请求 API；update-only（默认）仅做版本更新检查；events上报功能使用事件（绑定安装时生成、基于时间戳的唯一 ID），但绝不上报你分析的数据本身。
• 事件上报的边界：根据 docs/RELEASE_0_6.md，仅在privacy设为events时才会发送事件遥测，前端 Segment 追踪器也只在该设置下开启；默认update-only模式不发送事件。
• offline 模式的联动：在 pygwalker/api/pygwalker.py 的PygWalker.__init__中，当GlobalVarManager.privacy == "offline"时会强制关闭 Kanaries 云工具（self.show_cloud_tool = False），从 UI 层保证完全离线。
• kanaries_token：用于启用分享图表、分享配置等 Kanaries 云服务；PygWalker构造时若未显式传入kanaries_api_key，会回退到全局配置中的 token。

许可与资源

• 本项目采用 Apache License 2.0 许可。
• 相关学术论文：PyGWalker: On-the-fly Assistant for Exploratory Visual Data Analysis（arXiv:2406.11637）。
• 可参考仓库内的 docs/ARCHITECTURE.md（Python 与前端两半如何构建与通信）、docs/DEVELOPMENT.md（热重载开发工作流）、docs/CONTRIBUTING.md（验证命令、CI 与打包）进行本地开发与贡献；R 语言用户可关注 GWalkR，偏好免代码离线桌面应用的用户可关注 PyGWalker Desktop。
• 完整的行为变化、废弃时间线与兼容策略，详见 docs/RELEASE_0_6.md。

总结

从pip install pygwalker到pyg.walk(df)，再到spec_path状态持久化与computation="kernel"大计算引擎切换，PyGWalker 将 Jupyter 中的探索性数据分析体验提升为类 Tableau 的拖拽交互。0.6 版本进一步引入了可复用的Walker对象、统一的computation计算模型、静态 HTML 导出与图表程序化导出 API，同时通过pygwalker config将隐私控制权完整交还用户。无论是本地 Notebook、Kaggle/Colab 云端环境，还是 Streamlit Web 应用，都可以基于上述模式快速搭建可视化分析工作流。

【免费下载链接】pygwalkerPyGWalker: Turn your dataframe into an interactive UI for visual analysis项目地址: https://gitcode.com/GitHub_Trending/py/pygwalker