通过Poetry发布的PyPI包在VSCode中无自动导入提示问题

算力阿峰

2026-7-8

VSCode Pylance无法识别PyPI包导入提示的解决办法

针对你用Poetry发布的PyPI包在VSCode里没导入提示、但PyCharm正常的问题，给你几个实用的排查步骤：

先确认包结构是否合规
确保你的包根目录下有__init__.py文件（哪怕是空的），Pylance依赖这个文件识别Python包。如果用了src布局（代码放在src/你的包名/下），检查Poetry的pyproject.toml里有没有正确配置：
```
packages = [{ include = "fooexperiment", from = "src" }]
```
配置错了会导致安装后包的路径不符合Pylance的识别逻辑。
强制刷新Pylance缓存
按Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（Mac），输入Python: Restart Language Server重启Pylance。如果还不行，手动删缓存：找到VSCode的Pylance扩展缓存目录（比如Windows是%USERPROFILE%\.vscode\extensions\ms-python.vscode-pylance-xxx\server\cache，Mac/Linux是~/.vscode/extensions/ms-python.vscode-pylance-xxx/server/cache），删掉里面的文件后重启VSCode。
检查Pylance核心配置
打开settings.json，先把之前加的python.analysis.extraPaths和python.autoComplete.extraPaths注释掉——多余的路径配置反而可能干扰Pylance的自动识别。然后确认：
- python.analysis.typeCheckingMode不要设为off，至少改成basic，关闭类型检查会影响提示功能；
- 可以给目标包加深度解析配置，让Pylance深入遍历包结构：
```
"python.analysis.packageIndexDepths": {
    "fooexperiment": 2
}
```
验证安装的包完整性
终端里跑pip show fooexperiment找到安装路径，打开后确认里面有源代码文件（.py）或者类型提示文件（.pyi）。如果只有编译后的.pyc文件，Pylance没法解析提示。要是包本身没带类型提示，也可以在项目根目录建pyrightconfig.json，手动指定包的路径。