isort通过内置第三方包名列表（如requests、numpy）匹配导入路径前缀识别第三方库，未收录的新包默认归为localfolder；需在pyproject.toml中正确配置known_third_party数组和sections顺序，且确保项目根目录运行以避免相对导入误判。
isort 怎么识别第三方库
isort 不靠安装记录或 pip list 判断第三方库，而是按导入路径的「包名前缀」匹配预设的「标准库名单」和「已知第三方名单」。它内置了约 400 个常见第三方包名（比如 requests、numpy、django），只要导入语句是 import requests 或 from pandas import DataFrame，就归入 THIRDPARTY 组。
这个机制意味着：没被 isort 内置收录的新包（比如刚发布的 pydantic-settings），默认会被当成本地模块（LOCALFOLDER）——这是最常被忽略的错位来源。
- 检查是否被识别：运行
isort --show-config | grep known_third_party，看输出里有没有你的包名 - 新包必须手动加到配置的
known_third_party列表，不能指望 isort 自动发现 - 包名要写对：是
pydantic，不是pydantic-core；是httpx，不是httpx._api
如何在 pyproject.toml 里正确配置分组顺序
isort 的分组逻辑依赖 sections 和 known_* 配置项的严格配对。只改 known_third_party 不够，还必须确保 sections 中定义了对应 section 名（如 "THIRDPARTY"），且顺序合理。
典型错误是把 THIRDPARTY 放在 FIRSTPARTY 后面，结果本地模块反而排在第三方前面——isort 按 sections 列表顺序输出分组，不按“重要性”或“依赖层级”。
立即学习“Python免费学习笔记（深入）”；
-
sections = ["FUTURE", "STDLIB", "THIRDPARTY", "FIRSTPARTY", "LOCALFOLDER"]是安全顺序 -
known_third_party = ["requests", "click", "typer"]必须是字符串列表，不能带空格或换行符 - 如果用了
force_sort_within_sections = true，同一组内仍会按字母排序，不影响跨组位置
为什么 from . import xxx 被归进 THIRD PARTY
这种写法触发的是 isort 的「相对导入检测失效」：当 isort 无法确认当前文件所属包结构（比如没找到 pyproject.toml 或 setup.py，或文件不在包目录下），它会退化为纯字符串分析，把 from . import utils 中的 . 当作未知前缀，最终 fallback 到 THIRDPARTY。
这不是 bug，是 isort 对项目上下文缺失时的保守策略。真实项目中，这通常说明运行 isort 的路径不对，或缺少 src 目录声明。
- 确保在项目根目录运行
isort（即有pyproject.toml的那层） - 若代码在
src/myapp/下，需配置src_paths = ["src"]，否则 isort 看不到包边界 - 避免在 IDE 插件里单独格式化单个文件——它可能丢失项目级上下文
自定义分组时容易踩的兼容性坑
isort v5.12+ 把 known_* 配置从字符串升级为数组，但旧版配置（如 known_third_party="requests,numpy"）在新版里会被静默忽略，导致所有包都掉进 LOCALFOLDER —— 错误不报，格式却全乱。
另一个隐形问题是 Python 版本与 isort 版本错配：pyproject.toml 里的 [tool.isort] 在 isort
- 用
isort --version确认版本，v5.12+ 推荐统一用数组写法：known_third_party = ["requests"] - 检查配置是否生效：
isort --show-config | grep known_third_party，输出为空就是没加载成功 - CI 里务必锁定 isort 版本，比如
isort==5.13.2，避免自动升级引入行为变化
分组策略真正难的不是写配置，而是让 isort 理解你的项目结构。一旦路径、src 声明、配置加载顺序里有一环断掉，它就会按最简规则硬套，而那个规则跟你脑子里想的“第三方”根本不是一回事。
