VSCode中Python导入mypackage报ModuleNotFoundError的解决方法

问题背景 #

项目结构：

└── myproject
    ├── mypackage
        ├── __init__.py
        ├── a.py
        ├── b.py

在VSCode中打开myproject文件夹，直接运行a.py（代码包含from mypackage import b）时，报错ModuleNotFoundError: No module named 'mypackage'，但VSCode能正常识别该模块并高亮代码。需要将myproject作为包使用，因此import b无法满足需求，且已发现通过python3 -m mypackage.a（在myproject根目录执行）可正常运行。

原因分析 #

1. Python解释器的模块查找逻辑 #

Python依赖sys.path列表定位模块。当直接运行a.py时，Python会自动将a.py所在的目录（即myproject/mypackage）添加到sys.path，不会将上级的myproject目录纳入。此时sys.path中缺少myproject，自然找不到mypackage这个顶级包。

2. VSCode能识别模块的原因 #

VSCode的Python语言服务会自动将当前打开的根目录（myproject）纳入代码分析路径，因此能识别mypackage模块并提供语法高亮、代码提示。但这个分析路径和Python解释器运行时的sys.path相互独立，所以会出现“编辑器识别但运行报错”的矛盾情况。

3. python3 -m mypackage.a有效的原因 #

使用-m参数运行时，Python会将当前工作目录（执行命令时所在的myproject目录）添加到sys.path，再以模块方式加载mypackage.a。此时sys.path包含myproject，就能正确找到mypackage顶级包。

其他可选解决方法 #

除了-m参数的方式，还可以通过以下方式调整：

• 手动修改sys.path：在a.py开头添加代码，将myproject目录加入路径：

  import sys
  from pathlib import Path
  # 获取当前文件的父目录的父目录（即myproject）
  sys.path.append(str(Path(__file__).parent.parent))
  
  from mypackage import b
  

• 设置PYTHONPATH环境变量：
  Linux/macOS终端执行：

  export PYTHONPATH=/path/to/myproject
  

  Windows终端执行：

  set PYTHONPATH=C:\path\to\myproject
  

  设置后再运行a.py即可。

总结 #

核心差异在于VSCode的代码分析路径和Python解释器运行时的sys.path不一致。推荐优先使用python3 -m mypackage.a的方式运行，这种方式更符合Python包管理规范，也避免了手动修改路径的繁琐。

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