VSCode Jupyter中Pylance无法显示本地导入函数的文档字符串

问题原因 #

Pylance是静态代码分析工具，sys.path.append("some/path")仅在代码运行时生效，静态分析阶段无法识别这个路径，因此出现导入解析错误，也无法读取函数的文档字符串。而Python脚本文件可能因VSCode自动识别项目结构或手动配置过路径，所以能正常工作。

解决方案 #

方案1：配置Pylance的额外搜索路径

直接在settings.json中添加本地模块所在路径到python.analysis.extraPaths，让Pylance静态分析时能找到该路径：

{
    "gitlens.defaultDateFormat": null,
    "editor.inlineSuggest.enabled": true,
    "python.defaultInterpreterPath": "~/opt/anaconda3/envs/test/bin/python",
    "python.languageServer": "Pylance",
    "python.analysis.autoSearchPaths": true,
    "python.analysis.extraPaths": [
        "./tools",
        "some/path"  // 添加上你的scripts文件夹所在路径，可写绝对路径或相对路径
    ],
    "editor.minimap.enabled": false,
    "github.copilot.enable": {
        "*": true,
        "yaml": true,
        "plaintext": false,
        "markdown": false
    }
}

修改后重启VSCode，Pylance就能识别到scripts模块，鼠标悬停时会显示文档字符串，导入错误提示也会消失。

方案2：使用.env文件设置PYTHONPATH

在项目根目录创建.env文件，写入模块路径，这样不仅Pylance能识别，运行时也无需手动sys.path.append：

PYTHONPATH=some/path

VSCode会自动读取.env文件中的环境变量，配置完成后重启VSCode即可生效。

方案3：确认Jupyter内核与VSCode解释器一致

有时候Jupyter使用的内核和VSCode设置的默认解释器不是同一个环境，导致路径不匹配：

• 打开Jupyter笔记本，点击右上角的内核名称（比如Python 3.9.12 ('test')）
• 选择Change Kernel，确保选中的内核路径和settings.json中的python.defaultInterpreterPath一致

内容的提问来源于stack exchange，提问作者Ahmed Elashry