在uv虚拟环境中, 通过Jupyter 使用 PyGWalker 链接本地Json

Created on 2026/01/08, by Sunny

在 uv 虚拟环境下通过 Jupyter 部署并使用 PyGWalker 的操作步骤如下，按执行顺序整理：

第一阶段：环境准备与包安装

  1. uv虚拟环境部署：
    • 新建一个目录，通过终端运行 uv init --bare 初始化
    • uv add notebook 在虚拟环境中安装 Jupyter
    • uv add pygwalker 在虚拟环境中安装PyGWalker。
  2. 启动 Jupyter：
    • 通过终端运行 uv run jupyter lab 或 uv run jupyter notebook，这样可以确保 Jupyter 在当前项目的虚拟环境沙盒中运行。

或者，在安装完 Jupyter 后, 先进入它. 然后在 `notebooks/Untitled.ipynb` 中的单元格（Cell）内直接运行 `!uv add pygwalker` 进行安装。

第二阶段：Notebook 配置

  1. 创建 Notebook 文件：
    • 在 Jupyter 管理界面（localhost:8888/tree）右上角点击 “New”，选择 “Python 3 (ipykernel)”。注意必须创建后缀名为 .ipynb 的 Notebook，而不是纯文本 .py 文件。
配置与切换内核（Kernel）

**重启内核**：在Jupyter中安装完新包后，必须点击菜单栏的 **Kernel -> Restart Kernel...** 刷新环境。

第三阶段：数据处理与启动 PyGWalker

  1. 准备 JSON 数据：
    • 通过 Jupyter 的 “Upload” 按钮将 JSON 文件上传至项目根目录。
  2. 编写并运行代码：
    • 在单元格中加入下面的代码后, ctrl+enter 执行, 会在下面渲染出图形界面, 且json文件中的数据已经摆入, 拖拽到xy轴即可产生对应的图形.
import json
import pandas as pd
import pygwalker as pyg

# 1. 先用 Python 标准库读取文件
with open("file.json", "r", encoding="utf-8") as f:
    entries = json.load(f)

# 2. 自动展平嵌套结构 (pd.json_normalize 是处理 JSON 的神兵利器)
df = pd.json_normalize(entries)

# 3. 启动
pyg.walk(df)

第四阶段：故障排除与界面操作

  1. 解决渲染卡顿（如 Loading 提示）：
    • 若界面显示“Loading Graphic-Walker UI”，先尝试 刷新浏览器页面 (F5)。
    • 若仍无效，尝试清理单元格输出（Clear Cell Output），或改用强制渲染模式：pyg.walk(df, spec_io_mode="json")。
  2. 交互式分析：
    • 界面加载后，从左侧字段列表中将数据字段拖拽到 Columns（列）或 Rows（行）中，即可自动生成统计图表。

在 uv 环境中使用 PyGWalker 就像是在一个私人定制的实验室（虚拟环境）里工作。你首先要确保实验设备（pygwalker 和内核）已经搬进了实验室并接通了电源（uv run 启动），接着要把实验原材料（JSON 数据）铺平放在实验台上（Pandas 展平），最后按下启动开关（pyg.walk），一个自动化的多功能分析仪表盘（可视化界面）就会呈现在你面前。