配置VS Code识别Python外部stub文件无效，如何解决？

核心配置要点及排查步骤 #

1. 确保Stub文件的目录结构与库导入路径匹配 #

Pylance要求stub文件的结构必须和实际库的导入层级完全一致：

• 如果代码中是import external_lib，那么stub文件需放在C:\Program Files\Stubs\external_lib\__init__.pyi（包形式），或直接为C:\Program Files\Stubs\external_lib.pyi（单文件库形式）。
• 禁止将所有pyi文件直接放在Stubs根目录，必须对应库的导入结构。

2. 修正Stub路径配置 #

调整.vscode/settings.json中的配置，确保路径格式正确且目录可访问：

{
    "python.languageServer": "Pylance",
    "python.analysis.stubPath": "C:/Program Files/Stubs",
    "python.analysis.extraPaths": ["C:/Program Files/Stubs"]
}

• 使用正斜杠/代替双反斜杠，避免转义问题。
• 同时配置python.analysis.extraPaths，让Pylance将该目录纳入Python路径扫描范围。

3. 重启语言服务器 #

修改配置后必须重启Pylance才能生效：

• 打开命令面板（Ctrl+Shift+P），输入Python: Restart Language Server并执行。

4. 排查权限与路径优先级 #

• 确认C:\Program Files\Stubs目录对VS Code有读取权限，若存在系统目录权限限制，可将stubs移至项目内的typings目录，再将配置路径改为相对路径./typings。
• 在VS Code设置中搜索python.analysis.stubPath，确认当前生效的是工作区配置而非用户配置，保证工作区配置优先级更高。

5. 验证Stub文件有效性 #

检查pyi文件语法是否正确，确保类、函数定义及类型注解与实际库完全匹配，无效的stub文件会被Pylance忽略。

内容的提问来源于stack exchange，提问作者Pierre-olivier Gendraud