Python项目目录结构引发ModuleNotFoundError的问题咨询

1. 为何无法运行？该如何修复？ #

Python查找模块时，只会从sys.path列表中的目录和系统site-packages目录搜索。直接执行python3 scripts/main.py时，Python会把scripts/目录（脚本所在目录）加入sys.path，但项目根目录不在其中，所以找不到src模块。

修复方案选其一即可：

• 临时添加路径：在main.py开头加入代码，把项目根目录加入sys.path：

  import sys
  from pathlib import Path
  # 获取项目根目录（scripts的父目录）
  sys.path.append(str(Path(__file__).parent.parent))
  

• 用模块方式运行：给scripts目录添加空的__init__.py，将其变为Python包，然后在项目根目录执行：

  python3 -m scripts.main
  

• 可编辑安装项目：在项目根目录创建pyproject.toml（内容见问题3），激活虚拟环境后执行：

  pip install -e .
  

  安装后src会被虚拟环境识别，可直接导入。

2. 运行main.py的目录是否会影响结果？ #

肯定会影响，核心原因是Python的sys.path会随运行方式和目录变化：

• 在项目根目录执行python3 scripts/main.py：sys.path包含scripts/目录，不包含项目根目录，找不到src。
• 在scripts目录内执行python3 main.py：sys.path同样只包含scripts/目录，还是找不到上层的src。
• 只有当项目根目录被加入sys.path时，才能直接导入src开头的模块，和运行目录无关。

3. 如何配置虚拟环境，让Python能识别src及其子模块？ #

有两种常用方式：

• 方式一：可编辑安装（推荐）
  1. 在项目根目录创建pyproject.toml文件，内容如下：

     [build-system]
     requires = ["setuptools>=61.0"]
     build-backend = "setuptools.build_meta"
     
     [project]
     name = "python-project-test"
     version = "0.1.0"
     packages = ["src"]
     

  2. 激活虚拟环境后，在项目根目录执行：

     pip install -e .
     

     这样src会被安装到虚拟环境的site-packages中，全局可导入。
• 方式二：设置PYTHONPATH环境变量
  激活虚拟环境后，编辑虚拟环境的激活脚本（比如.venv/bin/activate），添加一行：

  export PYTHONPATH="/path/to/your/python-project-test:$PYTHONPATH"
  

  替换为你的项目根目录绝对路径，之后每次激活虚拟环境时，项目根目录都会被自动加入sys.path。

4. 当前项目是否符合标准Python项目目录结构？若不符合，问题出在哪？ #

当前结构接近标准，但存在几个小问题：

• scripts目录不是Python包（缺少__init__.py），无法用python -m方式运行入口脚本，不符合可导入包的规范。
• 缺少项目配置文件：标准结构通常会在根目录包含pyproject.toml、README.md、requirements.txt等文件，用于管理项目依赖、构建和文档。
• 入口脚本的规范问题：标准做法是把核心代码放在src，通过pyproject.toml配置console_scripts提供命令行入口，而非直接运行scripts目录下的脚本。比如在pyproject.toml中添加：

  [project.scripts]
  my-app = "src.liblocal.module1:my_function"
  

  安装后可直接用my-app命令运行函数。

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