pandas profiling 已停维并重命名为 ydata-profiling，须卸载旧包、安装新包并改用 from ydata_profiling import profilereport；需确保 dataframe 非空、类型纯净，推荐加 minimal=true 调试，导出时指定 utf-8 编码防乱码，大表应禁用相关性等耗时计算。
Pandas Profiling 已于 2022 年正式停止维护，pandas-profiling 包已重命名为 ydata-profiling，直接安装旧包会触发弃用警告甚至报错——这是你跑不起来报告的最常见原因。
安装正确版本：别再 pip install pandas-profiling
现在必须用 ydata-profiling，它兼容 Pandas 1.5–2.x 和 Python 3.8–3.12，且持续更新。旧版在 Pandas 2.0+ 下会因 API 变更直接崩溃（比如 df.describe(include="all") 返回结构变化）。
- 运行
pip install ydata-profiling（不是pandas-profiling） - 导入时写
from ydata_profiling import ProfileReport，不是import pandas_profiling - 如果已有旧环境，先卸载：
pip uninstall pandas-profiling -y，再装新包
生成基础报告：三行代码跑通但要注意 DataFrame 状态
ProfileReport 构造函数对输入敏感：空 DataFrame、含大量 NaN 的列、或 object 类型中混入 bytes/None/混合类型，都可能让 ProfileReport(df) 卡住或抛出 TypeError: unhashable type: 'dict'。
- 确保
df不为空：len(df) > 0，否则报ValueError: No observations - 提前清理明显异常：
df = df.dropna(how="all")去掉全空行，df.select_dtypes("object").applymap(type).nunique()检查是否混入非字符串类型 - 最小可行示例：
profile = ProfileReport(df, minimal=True)—— 加minimal=True跳过相关性、分布拟合等耗时计算，适合调试
导出 HTML 报告：路径、编码与中文乱码问题
profile.to_file("report.html") 默认用 UTF-8 写入，但在 Windows 控制台或某些 IDE（如旧版 PyCharm）里，如果系统 locale 是 GBK，浏览器打开可能显示方块字。
- 显式指定编码：用
profile.to_file("report.html", encoding="utf-8") - 避免中文路径：不要写
to_file("我的报告.html")，路径中含空格或中文易触发OSError: [Errno 22] - 若需嵌入 Jupyter：
profile.to_widgets()（需 IPython ≥ 8.0），比profile.to_notebook_iframe()更稳定
定制分析范围：跳过慢操作或敏感字段
默认开启所有检测（包括高基数分类变量的频率表、数值列的 K-S 检验），大表（>5 万行或 >50 列）极易卡死或内存溢出。
- 禁用相关性计算：
ProfileReport(df, correlations=None) - 限制字符串列分析长度：
ProfileReport(df, strings={"length": False})关闭字符长度统计 - 屏蔽敏感列：
ProfileReport(df, variables={"descriptions": False}, sensitive=["id_card", "phone"])（注意sensitive参数仅在 v4.6+ 支持）
真正麻烦的不是生成报告，而是当数据里有嵌套 JSON 字段、Timestamp 时区混杂、或 category 类型未预设顺序时，ydata-profiling 会尝试解析失败并静默跳过——得靠 df.dtypes 和 df.iloc[0] 手动检查首行样本。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
