!!! 2026年4月更新 !!! - 版本 2.3.2：长期存在的问题已修复

---

只需两行代码，即可进行深入的探索性数据分析（目标分析、比较、特征分析、相关性分析）！

Sweetviz 是一个开源的 Python 库，只需两行代码就能生成精美且信息密集的可视化图表，从而快速启动探索性数据分析 (EDA)。输出结果是一个完全自包含的 HTML 应用程序。

该系统的核心功能是快速可视化目标值和比较数据集。它的目标是帮助用户快速分析目标变量的特征、训练数据与测试数据之间的差异，以及其他类似的数据特性分析任务。

使用方法和参数说明如下，您也可以在此处找到一篇详细介绍其功能并展示实际示例的文章。

Sweetviz 的开发仍在继续！ 如果您在使用过程中遇到任何数据、兼容性或安装问题，请随时告知我！感谢您在 此处的问题跟踪系统中报告任何 BUG，我也非常欢迎您在全新的 GitHub “Discussions” 标签页中提出关于使用方法和功能的反馈与疑问！在这里查看讨论区。

示例与引用

使用泰坦尼克号数据集的 HTML 报告示例

带有文档的 Colab 笔记本示例（Jupyter 或其他笔记本也应适用）

Medium 文章详细介绍了其功能

KD Nugget 文章：

功能

• 目标分析
  • 展示目标变量（例如泰坦尼克号数据集中的“Survived”）与其他特征之间的关系。
• 可视化与比较
  • 不同数据集（例如训练数据与测试数据）
  • 同一数据集中不同子集的特征（例如男性与女性）
• 混合类型关联
  • Sweetviz 能够无缝整合数值型（皮尔逊相关系数）、类别型（不确定性系数）以及类别-数值混合型（相关比率）等多种数据类型的关联分析，为所有数据类型提供尽可能全面的信息。
• 类型推断
  • 自动检测数值型、类别型和文本型特征，并支持手动覆盖。
• 汇总信息
  • 类型、唯一值、缺失值、重复行、最常见值。
  • 数值分析：
    • 最小值/最大值/范围、四分位数、均值、众数、标准差、总和、中位数绝对偏差、变异系数、峰度、偏度。

新增与亮点

• 版本 2.2：针对 Python 3.7+ 和 NumPy 各版本的重大兼容性更新。
• 版本 2.1：支持 Comet.ml。
• 版本 2.0：支持 Jupyter、Colab 及其他笔记本环境，并优化了报告的 缩放与垂直布局。

（有关这些功能的详细文档请见下文）

升级

有些人通过 pip 升级时遇到了一些不稳定的情况。为了从现有安装升级到最新版本，建议先运行 pip uninstall sweetviz，然后再重新安装。

安装

Sweetviz 目前支持 Python 3.6 及以上版本，以及 Pandas 0.25.3 及以上版本。报告输出使用基础的 os 模块，因此像 Google Colab 这样需要自定义文件操作的环境目前尚不支持，不过我们正在寻找解决方案。

使用 pip 安装

安装 Sweetviz 的最佳方式（除了从源码安装外）是使用 pip：

pip install sweetviz

安装问题及解决方法

在极少数情况下，用户报告了诸如 ModuleNotFoundError: No module named 'sweetviz' 和 AttributeError: module 'sweetviz' has no attribute 'analyze' 等错误。 在这种情况下，我们建议采取以下措施：

• 确保您的脚本中没有名为 sweetviz.py 的文件，因为这会干扰库的正常运行。删除或重命名该脚本（以及任何相关的 .pyc 文件），然后再次尝试。
• 尝试使用 pip uninstall sweetviz 卸载库，然后再重新安装。
• 问题可能源于同时使用多个 Python 版本，或者操作系统权限不足。以下 Stack Overflow 文章解决了许多此类问题：文章 1、文章 2、文章 3。
• 如果以上方法都无效，请在 GitHub 上提交一个问题。感谢您的耐心，这将有助于解决您和其他人的问题！

基本用法

创建报告的过程非常简单，只需两行代码：

1. 使用 analyze()、compare() 或 compare_intra() 方法创建一个 DataframeReport 对象。
2. 使用 show_xxx() 函数渲染报告。现在您可以选择 HTML 或 笔记本 报告格式，并调整缩放比例：（更多选项详情见下文）

第 1 步：创建报告

创建报告主要有 3 个函数：

• analyze(...)
• compare(...)
• compare_intra(...)

分析单个数据框（及其可选的目标特征）

要分析单个数据框，只需使用 analyze(...) 函数，然后调用 show_html(...) 函数：

import sweetviz as sv

my_report = sv.analyze(my_dataframe)
my_report.show_html() # 默认参数会生成到 "SWEETVIZ_REPORT.html"

运行后，这将在您的默认浏览器中输出一个 1080p 宽屏 HTML 应用程序：

可选参数

analyze() 函数可以接受多个其他参数：

analyze(source: Union[pd.DataFrame, Tuple[pd.DataFrame, str]],
            target_feat: str = None,
            feat_cfg: FeatureConfig = None,
            pairwise_analysis: str = 'auto',
            verbosity: str = 'default'):

• source: 可以是数据框（如示例所示），也可以是一个包含数据框和要在报告中显示的名称的元组。 例如：my_df 或 [my_df, "Training"]
• target_feat: 一个字符串，表示被标记为“目标”的特征名称。目前只有布尔型和数值型特征可以作为目标。
• feat_cfg: 一个 FeatureConfig 对象，用于指定在分析中需要跳过的特征，或强制指定为某种类型的特征。参数可以是单个字符串或字符串列表。参数包括 skip、force_cat、force_num 和 force_text。“force_”参数会覆盖内置的类型检测。可以这样构造：

feature_config = sv.FeatureConfig(skip="PassengerId", force_text=["Age"])

• verbosity: [新] 可设置为 full、progress_only（仅显示进度条，不显示报告生成信息）和 off（完全静默，除错误或警告外）。默认的详细程度也可以在 INI 覆盖文件的“General”标题下设置（详情请参阅下方的“配置文件”部分）。
• pairwise_analysis: 相关性和其他关联性分析可能需要二次时间复杂度（n^2）才能完成。默认设置（“auto”）会在数据集包含“association_auto_threshold”个特征之前无提示地运行。超过该阈值后，您需要显式传递参数 pairwise_analysis="on"（或 "off"），因为处理如此多的特征将耗费大量时间。此参数还涵盖了关联图的生成（基于 Drazen Zaric 的概念)：

比较两个数据框（例如测试集与训练集）

要比较两个数据集，只需使用 compare() 函数。其参数与 analyze() 相同，只是增加了一个用于覆盖比较数据框的第二个参数。建议使用 [数据框, "名称"] 格式的参数，以便更好地区分基准数据框和比较数据框。（例如：[my_df, "Train"] 与 my_df）

my_report = sv.compare([my_dataframe, "Training Data"], [test_df, "Test Data"], "Survived", feature_config)

比较同一数据框中的两个子集（例如男性与女性）

获取深刻洞察的另一种方法是使用比较功能将数据集拆分为两个子群体。

为此提供了内置支持，即 compare_intra() 函数。该函数的一个参数是布尔系列，另一个参数是用于命名结果数据集（真、假）的显式“名称”元组。请注意，内部会创建两个独立的数据框来分别表示每个子组。因此，它更像是手动执行此类处理的一种快捷方式。

my_report = sv.compare_intra(my_dataframe, my_dataframe["Sex"] == "male", ["Male", "Female"], "Survived", feature_config)

第 2 步：展示报告

一旦您创建了报告对象（例如上述示例中的 my_report），只需将其传递给以下两个 show 函数之一：

show_html()

show_html(  filepath='SWEETVIZ_REPORT.html', 
            open_browser=True, 
            layout='widescreen', 
            scale=None)

show_html(...) 会按照给定的文件路径创建并保存 HTML 报告。可选项包括：

• layout: 可以是 'widescreen' 或 'vertical'。宽屏布局在鼠标悬停于每个特征时，会在屏幕右侧显示详细信息。2.0 版本新增的垂直布局在水平方向上更加紧凑，并允许通过单击展开每个详细信息区域。
• scale: 使用浮点数（例如 scale = 0.8 或 None）来缩放整个报告。这对于使报告适应任何输出非常有用。
• open_browser: 启用自动打开网页浏览器以显示报告的功能。由于在某些情况下可能不希望自动打开浏览器（或者会导致某些 IDE 出现问题），您可以在此处将其禁用。

show_notebook()

show_notebook(  w=None, 
                h=None, 
                scale=None,
                layout='widescreen',
                filepath=None,
                file_layout=None,
                file_scale=None)

show_notebook(...) 是 2.0 版本新增的功能，它会将一个 IFRAME 元素嵌入到笔记本中（例如 Jupyter、Google Colab 等），直接显示报告。

请注意，由于笔记本环境通常视觉空间较为有限，因此最好使用自定义的宽度/高度/缩放值（w、h、scale），甚至可以在 INI 覆盖文件中设置自定义默认值（见下文）。可选项包括：

• w（宽度）：设置报告输出窗口的宽度（完整报告可能无法完全显示；请使用 layout 和/或 scale 来调整报告本身）。可以是百分比字符串（w="100%"）或像素数（w=900）。
• h（高度）：设置报告输出窗口的高度。可以是像素数（h=700）或“Full”，以使窗口高度与所有特征对齐（h="Full"）。
• scale：与上述 show_html() 中的缩放选项相同。
• layout：与上述 show_html() 中的布局选项相同。
• filepath：可选的输出 HTML 报告。
• file_layout：仅针对可选文件输出的布局（与上述 show_html() 中的布局选项相同）。
• file_scale：仅针对可选文件输出的缩放比例（与上述 show_html() 中的缩放选项相同）。

自定义默认值：配置文件

该软件包包含一个用于配置的 INI 文件。您可以通过提供自己的配置文件并在创建报告之前调用以下代码来覆盖任何设置：

sv.config_parser.read("Override.ini")

重要提示 #1： 最好在执行任何其他命令之前加载覆盖配置，因为许多 INI 选项都会在报告生成过程中被使用。

重要提示 #2： 在您的覆盖 INI 文件中，务必在一组数值之前放置标题行（例如 [General]），否则您的设置将被忽略。请参阅下面的示例。如果设置多个值，只需包含一次 [General] 行即可。

最有用的配置覆盖

您可以查看 sweetviz_defaults.ini 文件，了解哪些内容可以被覆盖（警告：其中许多内容仍在开发中，文档也不完善），但最有用的覆盖项如下。

默认报告布局和尺寸

您可以覆盖以下任何一项（将其放入您自己的 INI 文件中，请勿忘记文件头），以避免每次执行 show 命令时都需手动设置：

重要提示：如果指定百分比，请使用双百分号 %%。

[Output_Defaults]
html_layout = widescreen
html_scale = 1.0
notebook_layout = vertical
notebook_scale = 0.9
notebook_width = 100%%
notebook_height = 700

中日韩（CJK）字符支持

[General]
use_cjk_font = 1 

*如果为 [general] 设置多个值，只需包含一次 [General] 行。

这会将图表中的字体切换为支持 CJK 字符的字体。虽然这种字体可能不如其他字体紧凑，但它可以消除针对这些语言的所有警告和“未知字符”符号。

移除 Sweetviz 标志

[Layout]
show_logo = 0

这会移除页面顶部的 Sweetviz 标志。

设置默认详细程度

[General]
default_verbosity = off 

*如果为 [general] 设置多个值，只需包含一次 [General] 行。

可设置为 full、progress_only（仅显示进度条，不显示报告生成信息）和 off（完全静默，仅显示错误或警告）。

相关性/关联性分析

Sweetviz 关联性图和分析的一大洞察来源及独特之处在于，它将以下内容统一到一张图中（以及详细视图中）：

• 数值特征之间的数值相关性
• 类别型与类别型特征之间的不确定性系数
• 类别型与数值型特征之间的相关比率

正方形代表类别型特征之间的关系，圆形代表数值型特征之间的相关性。请注意，为了清晰起见，主对角线留空。

重要提示：由表示不确定性系数的正方形所展示的类别型与类别型特征之间的关联是非对称的，这意味着每一行代表的是行标题（左侧）对每一列能提供多少信息。例如，“Sex”、“Pclass”和“Fare”是对“Survived”贡献最大的因素。

对于泰坦尼克号数据集而言，这些信息相对对称，但并非总是如此！

相关性也会在每个特征的详细部分中显示，并在适用时突出显示目标值。例如：

最后需要注意的是，这些相关性/关联性方法不应被视为绝对真理，它们会对数据的底层分布和关系做出一些假设。然而，它们确实可以作为一个非常有用的起点。

Comet.ml 集成

自 2.1 版本起，Sweetviz 现已全面集成 Comet.ml。这意味着只要您的环境正确设置了 API 密钥，Sweetviz 将会自动记录使用 show_html() 和 show_notebook() 生成的所有报告到您的工作区。

此外，您还可以使用新函数 report.log_comet(experiment_object)，将特定实验的报告显式上传到您的工作区。

您可以参阅一个 Colab 笔记本，用于生成报告，以及其对应的 Comet.ml 工作区报告。

Comet 报告参数

您可以通过覆盖配置文件中的 [comet_ml_defaults] 部分，自定义 Sweetviz 报告在 Comet 工作区中的显示方式。有关使用 INI 覆盖的更多信息，请参阅上文。

您可以选择使用 widescreen（横向）或 vertical（纵向）布局，并设置您偏好的缩放比例，只需将以下内容放入您的覆盖 INI 文件中：

[comet_ml_defaults]
html_layout = vertical
html_scale = 0.85

故障排除 / 常见问题解答

• 安装问题

请参阅本文档顶部的“安装问题及解决方法”部分。

• 亚洲字符，“RuntimeWarning: 当前字体缺少符号 ###”

请参阅上述关于 CJK 字符支持的部分。如果您发现需要支持更多类型的字符，欢迎在问题跟踪系统中提交请求。

• …其他问题

由于开发仍在进行中，欢迎您随时在此处的问题跟踪系统或我们的论坛中报告任何问题和建议（您应该可以使用 GitHub 账户登录！）。

贡献

这是我第一个开源项目！我构建它的目的是使其成为尽可能有用的工具，帮助更多人完成数据科学工作。如果它对您有所帮助，您的贡献将不胜感激，并且形式多样：

1. 宣传推广！

在 GitHub 上给个项目加一颗星，或者在 Twitter 或 Instagram 上发布一条动态，都是最简单的贡献方式，却有可能极大地推动项目的发展！如果您觉得这个项目有用，这些小小的行动将意义重大，并能产生深远的影响。

Kaggle 笔记本/帖子、Medium 文章、YouTube 视频教程等需要更多时间，但效果会更好！

2. 报告漏洞和问题

随着越来越多的人使用该项目，并处理各种新的（甚至“脏”的）数据，预计会出现许多小问题。如果您发现了漏洞，请在此处新建一个问题。

3. 提供建议并讨论使用场景和功能

为了让 Sweetviz 更加实用，我们需要了解您希望它实现什么功能，或者如何改进。请前往我们的 Discourse 论坛发表您的建议；无需登录！。

4. 参与开发

我非常欢迎任何人在这项目上提供帮助，只需通过问题跟踪器和/或我们的 Discourse 论坛与我联系即可。

请注意，在经历了繁忙的开发期后，目前代码本身仍需进一步清理和完善。 :)

特别致谢及相关资料

贡献者

特别感谢所有在 GitHub 上通过报告、反馈和提交代码做出贡献的人！ 我要特别感谢 Frank Male，他在修复问题和搭建 2.2.0 的新构建流程方面给予了巨大帮助。

由 contrib.rocks 制作。

相关资料

我希望 Sweetviz 能成为一个汇聚业界最佳实践的中心，让人们无需从头开发就能获取最有价值的信息和可视化效果。

为此，我想分享一些曾给予我灵感并被整合进 Sweetviz 的优秀资源：

• Pandas-Profiling 是本项目的最初灵感来源。其部分类型检测代码已被直接纳入 Sweetviz。
• Shaked Zychlinski: 寻找分类变量的相关性 是一篇关于不同变量交互类型的精彩文章，也是 Sweetviz 中相关分析的基础。
• Drazen Zaric: 在 Python 中绘制更优秀的热力图与相关矩阵图 则为我们设计关联图提供了重要参考。

Sweetviz 快速上手指南

Sweetviz 是一个开源 Python 库，仅需两行代码即可生成美观、高密度的可视化报告，快速启动探索性数据分析（EDA）。它特别适用于分析目标变量特征、对比训练集与测试集，输出结果为独立的 HTML 文件或直接在 Notebook 中展示。

环境准备

• 操作系统：Windows, macOS, Linux
• Python 版本：3.6 及以上
• 核心依赖：
  • Pandas >= 0.25.3
  • NumPy (兼容版本)
• 运行环境：支持标准 Python 脚本、Jupyter Notebook 及 Google Colab。

安装步骤

推荐使用 pip 进行安装。为确保安装纯净，若之前安装过旧版本，建议先卸载再安装。

# 可选：如果之前安装过，建议先卸载以避免冲突
pip uninstall sweetviz

# 安装最新版
pip install sweetviz

提示：国内用户如遇下载缓慢，可添加国内镜像源加速安装：

pip install sweetviz -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

生成报告只需两个步骤：创建报告对象 和 渲染输出。

1. 最简单的单数据集分析

假设你有一个名为 df 的 Pandas DataFrame，想要分析其中 "Survived" 列作为目标变量：

import sweetviz as sv

# 步骤 1: 创建报告对象
# target_feat 指定目标列名（仅支持数值型或布尔型）
my_report = sv.analyze(df, target_feat="Survived")

# 步骤 2: 生成并打开 HTML 报告
# 默认生成 "SWEETVIZ_REPORT.html" 并在浏览器打开
my_report.show_html()

2. 对比两个数据集（如训练集 vs 测试集）

import sweetviz as sv

# 对比训练集和测试集，建议为数据框指定名称以便区分
my_report = sv.compare(
    [train_df, "Training Data"], 
    [test_df, "Test Data"], 
    target_feat="Survived"
)

my_report.show_html()

3. 在 Jupyter Notebook / Colab 中直接展示

如果你希望在 Notebook 单元格内直接查看报告，而非弹出浏览器：

import sweetviz as sv

my_report = sv.analyze(df, target_feat="Survived")

# 在 Notebook 中嵌入显示
# w/h 可设置宽高，scale 可调整缩放比例
my_report.show_notebook(w=1000, h=800, scale=0.8)

关键参数说明

• target_feat: 指定需要重点分析的目标列（如预测标签）。
• layout: 在 show_html 或 show_notebook 中设置，可选 'widescreen' (宽屏，默认) 或 'vertical' (垂直紧凑布局)。
• scale: 浮点数，用于整体缩放报告大小（例如 0.8 缩小至 80%），适应不同屏幕。
• feat_cfg: 高级配置，可用于跳过某些列或强制指定列的数据类型（如将数值型强制视为分类别）。