PyCharm与命令行执行Python项目出现src模块找不到的原因及解决方法

PyCharm会自动把项目根目录加入Python的模块搜索路径（sys.path），所以你在IDE里运行时，Python能识别到src作为一个合法的包。但命令行直接执行python src\main.py时，Python只会把main.py所在的src目录加入sys.path，而非项目根目录。这时候代码里写from src.xxx import ...，Python找不到src这个包，自然就报ModuleNotFoundError了。

下面是几种实用的解决方式，按需选择：

• 设置PYTHONPATH环境变量
  激活虚拟环境后，先把项目根目录添加到PYTHONPATH：
  Windows命令行：

  set PYTHONPATH=你的项目根目录绝对路径;%PYTHONPATH%
  

  Linux/macOS终端：

  export PYTHONPATH=/你的项目根目录绝对路径:$PYTHONPATH
  

  之后再执行python src/main.py就能正常导入模块了。

• 以模块方式运行脚本
  切换到项目根目录，用-m参数运行：

  python -m src.main
  

  这种方式会自动把当前目录（项目根目录）加入sys.path，Python会将src视为一个包，内部模块的导入就能正常工作。

• 在main.py中手动添加路径
  在main.py的最顶部加入以下代码，强制把项目根目录加入搜索路径：

  import sys
  from pathlib import Path
  
  # 定位项目根目录（src的父目录）
  project_root = Path(__file__).parent.parent
  sys.path.append(str(project_root))
  

  这样不管从哪个路径启动main.py，都能确保Python找到src包。

• 改用相对导入（不推荐）
  把导入语句改成相对路径形式，比如from .xxx import ...（.代表当前文件所在目录）。但这种方式在直接运行main.py时容易触发ImportError，更适合项目作为包被其他程序导入的场景，单独运行脚本时不建议用。

内容的提问来源于stack exchange，提问作者Andrii's Quest