python 3.11 标准库中无内置 toml 模块，故 import toml 报 modulenotfounderror；正确方式是使用 python 3.11+ 新增的 import tomllib。
Python 3.11 标准库中没有内置的 toml 模块——这是常见误解的根源。你不能直接 import toml 并期待它工作。
为什么 import toml 会报错：ModuleNotFoundError
尽管 PEP 518 和 PEP 621 推动了 TOML 在 Python 生态中的普及（如 pyproject.toml），但截至 Python 3.11，标准库仍未包含原生 TOML 解析器。官方明确表示暂不计划加入，理由包括解析器实现复杂、安全边界难界定、以及已有成熟第三方方案。
-
import toml→ 触发ModuleNotFoundError: No module named 'toml' -
import tomllib是正确路径（Python 3.11+ 新增） - 旧版本（tomli 或
tomlkit
用 tomllib 读取配置文件的正确写法
tomllib 是 Python 3.11 引入的标准库模块，只提供解析（load），不支持序列化（dump）。它设计为只读、安全、轻量，适合加载配置。
- 必须以文本模式打开文件，并指定
encoding='utf-8'（TOML 规范要求 UTF-8） - 使用
tomllib.load()（文件对象）或tomllib.loads()（字符串） - 不支持注释保留、格式化写入或修改后保存
import tomllib
<p>with open("config.toml", "rb") as f: # 注意：必须用 binary mode
config = tomllib.load(f)</p><p>print(config["database"]["host"]) # 示例访问
</p>
⚠️ 关键细节：tomllib.load() 要求文件以 "rb" 模式打开，不是 "r" —— 它内部按字节解析并自行解码，传入文本流会报错。
tomllib vs tomli：什么情况下该换第三方库？
如果你需要以下任一能力，tomllib 就不够用了，得切到 tomli（兼容 3.7+，API 与 tomllib 几乎一致）或更重的 tomlkit：
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
- 在 Python 3.10 或更早版本运行代码
- 需要保留注释、空行、原始格式（
tomlkit支持 round-trip parsing） - 要修改配置后写回文件（
tomllib完全不提供dump） - 依赖某些
tomlkit特有功能，如位置追踪、自定义 encoder
安装 tomli（推荐用于跨版本兼容）：pip install tomli；之后只需改一行导入：import tomli as tomllib，其余代码不变。
常见解析失败原因和调试建议
TOML 语法比 JSON 更灵活，但也更容易因格式疏忽出错。遇到 tomllib.TOMLDecodeError 时，优先检查：
- 行尾是否有不可见的
\r或 BOM（尤其 Windows 编辑器保存时）→ 用file -i config.toml或 VS Code 查看编码 - 表头（如
[database]）前后是否夹杂空行或缩进（合法，但某些编辑器会误加空格） - 字符串值是否漏掉引号（
path = data/❌，应为path = "data/"✅） - 日期时间字面量格式错误（
2023-10-05T14:30:00Z合法，2023/10/05不合法）
调试技巧：把文件内容先读成字符串，用 tomllib.loads() 替代 load()，便于插入 print(repr(content[:100])) 定位坏字符。
真正容易被忽略的是二进制打开这个硬性要求，以及 tomllib 的单向性——它只管读，不管写，也不管你后续想怎么改配置。别指望它能替代 tomlkit 做配置管理。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
