Python导入在IDE与PowerShell中表现不一致的原因及解决方法

项目结构 #

repo-name
|_ .github
|_ actual_code
  |_ __init__.py
  |_ main.py
  |_ constants.py
|_ Dockerfile
|_ virtual_environment
|_ other stuff

问题现象 #

• 当main.py中使用from actual_code.constants import CONSTANT_A, CONSTANT_B：
  • PyCharm社区版控制台能正常运行
  • PowerShell执行python actual_code/main.py时抛出ModuleNotFoundError
• 改成from constants import CONSTANT_A, CONSTANT_B：
  • IDE控制台运行失败
  • PowerShell能正常执行

两种环境的工作目录均为repo-name，需求如下：
A) 问题产生的原因；
B) 解决方法，避免频繁修改导入语句。

A) 问题原因 #

核心差异在于Python的模块搜索路径（sys.path）在两种环境下的配置不同：

1. PyCharm环境：PyCharm默认会把项目根目录（repo-name）添加到sys.path中，此时actual_code被识别为一个顶层可导入模块，所以from actual_code.constants import ...能正常找到对应的文件。
2. PowerShell直接运行脚本：执行python actual_code/main.py时，Python会自动把脚本所在的目录（actual_code）加入sys.path的最前端，而非项目根目录。这时actual_code不在搜索路径里，所以from actual_code.constants会报错；但constants.py和main.py在同一目录，因此from constants import ...能直接找到模块。

B) 解决方法 #

方法1：用相对导入+包方式运行（推荐）

在main.py中改用相对导入：

from .constants import CONSTANT_A, CONSTANT_B

然后在repo-name目录下，以包的方式运行脚本：

python -m actual_code.main

这种方式下，PyCharm和PowerShell的行为会完全一致——-m参数会强制Python把项目根目录加入sys.path，同时触发包的相对导入逻辑，不管在IDE还是终端都能正常运行。

方法2：手动添加项目根目录到sys.path

在main.py的最顶部加入以下代码，主动把项目根目录加入搜索路径：

import sys
from pathlib import Path

# 获取当前脚本所在目录的父目录（即repo-name）
project_root = Path(__file__).parent.parent
sys.path.append(str(project_root))

# 之后正常使用绝对导入即可
from actual_code.constants import CONSTANT_A, CONSTANT_B

这种方式不需要改变原有运行命令，不管是PyCharm直接运行还是PowerShell执行python actual_code/main.py，都能兼容。

方法3：设置PYTHONPATH环境变量

在PowerShell中临时设置环境变量，把项目根目录加入：

$env:PYTHONPATH = "你的repo-name绝对路径"
python actual_code/main.py

如果需要永久生效，可以根据Windows系统的环境变量设置流程，把PYTHONPATH设为repo-name的路径，这样每次运行脚本时，Python都会自动把项目根目录加入搜索路径，和PyCharm的默认行为对齐。

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