Python src目录下导入同级包遇ModuleNotFoundError及相关问题咨询

问题背景 #

从Matlab转向Python科学计算，使用VS Code+PyLint，项目结构如下：

my_project/
└── src/
    ├── analysis_pkg/
    │   ├── __init__.py
    │   ├── utils.py            # 定义load_velocity_data(), interpolate_nan()
    │   └── dissipation.py      # 定义dissipation_gerbi()
    └── scripts/
        └── process_all.py 

在process_all.py中导入模块时出现PyLint的E0401导入错误，仅能通过python -m scripts.process_all在scripts目录下运行脚本。

1. 报错原因及解决方法 #

报错原因

PyLint和Python解释器找不到analysis_pkg，核心原因是Python的模块搜索路径（sys.path）未包含src目录：

• 直接在scripts目录下运行python process_all.py时，当前目录（scripts）会被加入sys.path，但analysis_pkg在上级的src目录里，所以无法识别；
• 用-m参数运行时，Python会自动把当前工作目录（my_project）加入sys.path，因此能找到模块，但PyLint默认未将src目录纳入搜索路径，所以抛出导入错误。

解决方法

• VS Code配置PyLint路径（推荐长期用）：
  在项目根目录（my_project）下创建.vscode/settings.json，添加以下内容，将src目录手动加入PyLint的搜索路径：

  {
      "python.linting.pylintArgs": [
          "--init-hook",
          "import sys; sys.path.insert(0, './src')"
      ]
  }
  

• 临时应急方案：
  在process_all.py开头添加代码，动态将src目录加入sys.path：

  import sys
  from pathlib import Path
  sys.path.append(str(Path(__file__).parent.parent))
  

2. 当前项目结构是否高效优雅？ #

这个结构属于半规范的过渡型结构，有可取之处但也有优化空间：

• 优点：区分了功能包（analysis_pkg）和执行脚本（scripts），符合Matlab用户的代码组织习惯，逻辑清晰。
• 缺点：缺少Python项目标准结构的必要组件，比如：
  • 根目录的pyproject.toml（管理依赖、构建配置）
  • tests/目录（存放单元测试代码）
  • data/目录（分离原始/处理后数据，避免和代码混放）
  • README.md（项目说明文档）

优化后的推荐结构：

my_project/
├── src/
│   └── analysis_pkg/
│       ├── __init__.py
│       ├── utils.py
│       └── dissipation.py
├── scripts/
│   └── process_all.py
├── tests/
│   └── test_utils.py
├── data/
│   ├── raw/
│   └── processed/
├── pyproject.toml
└── README.md

3. 跨目录导入的正确方式及脚本运行场景 #

正确导入方式

核心原则是让Python能定位到包所在目录，推荐两种标准方案：

1. 将src目录设为全局搜索路径
   • 方式一：在项目根目录执行pip install -e .（需先编写pyproject.toml），把analysis_pkg安装为可编辑包，此时Python全局可识别该包，你当前的导入语句无需修改。
   • 方式二：通过环境变量临时设置，终端运行脚本前执行：

     # Linux/macOS
     export PYTHONPATH="./src:$PYTHONPATH"
     # Windows cmd
     set PYTHONPATH=./src;%PYTHONPATH%
     # Windows PowerShell
     $env:PYTHONPATH = "./src;" + $env:PYTHONPATH
     

2. 包内相对导入（仅适用于包内部模块）
   如果是analysis_pkg内部模块互相调用，可用相对路径，比如在dissipation.py中导入utils的函数：

   from .utils import load_velocity_data
   

不同场景下运行process_all.py

• VS Code开发调试：
  配置.vscode/launch.json，指定工作目录和PYTHONPATH，直接点击运行按钮即可：

  {
      "version": "0.2.0",
      "configurations": [
          {
              "name": "Python: Process All",
              "type": "python",
              "request": "launch",
              "program": "${workspaceFolder}/scripts/process_all.py",
              "cwd": "${workspaceFolder}",
              "env": {"PYTHONPATH": "${workspaceFolder}/src"}
          }
      ]
  }
  

• 终端运行：
  • 方法一：在my_project目录下，设置PYTHONPATH后直接运行：

    # Linux/macOS
    export PYTHONPATH="./src" && python scripts/process_all.py
    # Windows
    set PYTHONPATH=./src && python scripts/process_all.py
    

  • 方法二：使用-m参数（你当前的方式），在my_project目录下执行：

    python -m scripts.process_all
    

  • 方法三：安装为可编辑包后，可在任意目录直接运行脚本（需确保scripts路径正确）。

4. python -m scripts.process_all是否为最优方式？ #

这是推荐的标准方式之一，但并非唯一最优解，优缺点如下：

• 优点：
  • 无需手动设置PYTHONPATH，Python会自动将当前工作目录加入sys.path，避免路径混乱；
  • 符合Python模块运行规范，减少直接运行脚本导致的路径问题。
• 缺点：
  • 必须在项目根目录（my_project）下执行，路径限制较强；
  • 新手可能不习惯模块式运行的写法。

如果追求灵活性，推荐结合pyproject.toml配置可编辑安装，安装后可在任意目录运行脚本，同时彻底解决导入问题，这是Python项目的标准实践。

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