AGgrid报错：ModuleNotFoundError: No module named 'st_aggrid'

Question

在使用 Streamlit 集成 AG Grid 时，开发者常遇到 `ModuleNotFoundError: No module named 'st_aggrid'` 错误。该问题通常源于未正确安装 `st-aggrid` 包。尽管包导入语句为 `from st_aggrid import AgGrid`，但其实际安装命令为 `pip install streamlit-aggrid`，而非直觉中的 `pip install st_aggrid`。此外，部分虚拟环境或 Jupyter 内核未激活导致安装路径错误，也会引发此异常。需确保在正确的 Python 环境中执行安装，并验证是否包含依赖项如 `pyarrow`。某些情况下，即使安装后仍报错，可能是由于版本兼容性问题或 IDE 缓存未更新，建议重启内核并检查包是否出现在 `pip list` 中。

Answer 1

1. 问题背景与常见错误现象

在使用 Streamlit 构建交互式数据应用时，AG Grid 是一个功能强大的表格组件，支持排序、过滤、编辑、分页等高级特性。开发者通常通过 st-aggrid 包来集成 AG Grid，但初学者常遇到如下报错：

ModuleNotFoundError: No module named 'st_aggrid'

该异常表明 Python 解释器无法找到名为 st_aggrid 的模块。尽管导入语句为 from st_aggrid import AgGrid，但其对应的安装包名称却是 streamlit-aggrid，这造成了命名不一致的认知偏差。更复杂的是，即便执行了安装命令，仍可能因环境隔离或依赖缺失而持续报错。

2. 安装路径与命名差异解析

Python 包的发布名称（PyPI）与导入名称常常不一致，这是导致混淆的根本原因之一。以下是关键信息对比：

用途	Pip 安装命令	Python 导入语句
AG Grid 集成包	pip install streamlit-aggrid	from st_aggrid import AgGrid
Streamlit 核心库	pip install streamlit	import streamlit as st

注意：不能使用 pip install st_aggrid 或 pip install st-aggrid（拼写错误），必须使用正确的 PyPI 包名 streamlit-aggrid。

3. 虚拟环境与内核管理问题排查

现代开发中广泛使用虚拟环境（如 venv、conda）和 Jupyter 内核，若未正确激活目标环境，pip install 将安装到默认全局或错误环境中，导致模块不可见。以下是典型排查步骤：

1. 确认当前 Python 环境：which python 或 where python（Windows）
2. 检查是否处于虚拟环境：echo $VIRTUAL_ENV
3. 列出已安装包：pip list | grep streamlit-aggrid
4. 验证 Jupyter 内核绑定：jupyter kernelspec list
5. 必要时重新安装内核：python -m ipykernel install --user --name=myenv
6. 重启 Jupyter Notebook 或 VS Code 内核
7. 确保 IDE 使用的是正确的解释器路径
8. 检查 conda 环境（如使用）：conda activate myenv
9. 运行 pip show streamlit-aggrid 查看安装位置
10. 确认 site-packages 是否在 sys.path 中

4. 依赖项与版本兼容性分析

streamlit-aggrid 依赖多个底层库，其中最重要的是 pyarrow，用于高效数据序列化。缺失此依赖可能导致运行时异常或静默失败。可通过以下命令验证：

pip install pyarrow

此外，版本不匹配也是常见陷阱。例如：

• Streamlit >=1.20 与 streamlit-aggrid <=0.3.x 存在渲染兼容性问题
• 某些旧版 st-aggrid 不支持 Streamlit 的新组件模型
• 推荐使用最新稳定版本：pip install streamlit-aggrid==0.4.2

建议在项目根目录创建 requirements.txt 文件统一管理：

streamlit==1.28.0
streamlit-aggrid==0.4.2
pyarrow==14.0.0
pandas>=1.5.0

5. 故障诊断流程图

graph TD
    A[ModuleNotFoundError: No module named 'st_aggrid'] --> B{已执行 pip install?}
    B -->|否| C[运行 pip install streamlit-aggrid]
    B -->|是| D{是否在正确环境中安装?}
    D -->|否| E[激活虚拟环境/conda env]
    D -->|是| F{pip list 是否显示 streamlit-aggrid?}
    F -->|否| G[检查 Python 路径与 site-packages]
    F -->|是| H{IDE/Jupyter 是否使用相同内核?}
    H -->|否| I[重新配置内核或解释器]
    H -->|是| J{是否安装 pyarrow?}
    J -->|否| K[pip install pyarrow]
    J -->|是| L[重启内核并重试]
    L --> M[问题解决]

6. 实际代码示例与最佳实践

以下是一个完整的 Streamlit 应用片段，展示如何正确集成 AG Grid：

import streamlit as st
from st_aggrid import AgGrid, GridOptionsBuilder
import pandas as pd

# 示例数据
df = pd.DataFrame({
    'Name': ['Alice', 'Bob'],
    'Age': [25, 30]
})

# 构建网格选项
gb = GridOptionsBuilder.from_dataframe(df)
gb.configure_default_column(editable=True)
grid_options = gb.build()

# 渲染 AG Grid
AgGrid(
    dataframe=df,
    gridOptions=grid_options,
    enable_enterprise_modules=False,
    height=200
)

部署前务必在目标环境中测试导入可用性，并考虑使用 Docker 镜像固化依赖环境，避免“在我机器上能运行”的问题。