配置正确sys.path与conda环境仍遇Python ModuleNotFoundError问题

我正在开发一个Python项目，项目结构如下：

apx-cv/
├── utils/
│   └── custom_object_functions.py
│   └── utils.py
├── models/
│   └── sample_configurations.py
└── test/
    └── run_files_ee-opt.py

utils目录包含各类工具函数，我尝试在test目录下的run_files_ee-opt.py中导入模块：

from utils.custom_object_functions import create_hollow_room, get_arrow, create_coordinate_axes_mesh

# Rest of the code...

在apxcv conda环境中，从项目根目录apx-cv执行命令：

python test/run_files_ee-opt.py

出现错误：

ModuleNotFoundError: No module named 'utils'

PyCharm中运行正常，但本地及远程终端运行均失败，所有模块（utils、models等）都无法导入。已尝试以下操作：

• 验证sys.path：确认包含当前工作目录的空字符串''
• 使用绝对导入而非相对导入
• 确认运行脚本时工作目录为项目根目录
• 移除utils相关方法后仍无法导入models

1. 为目录添加__init__.py文件 #

Python需要目录下有__init__.py才能将其识别为可导入的包。在utils/、models/、test/目录下都创建空的__init__.py文件，结构变为：

apx-cv/
├── utils/
│   ├── __init__.py
│   ├── custom_object_functions.py
│   └── utils.py
├── models/
│   ├── __init__.py
│   └── sample_configurations.py
└── test/
    ├── __init__.py
    └── run_files_ee-opt.py

PyCharm能正常运行的原因之一是它会自动将标记为源根的目录视为包，而终端环境需要显式的__init__.py文件。

2. 运行脚本时使用-m参数 #

从项目根目录运行脚本时，改用模块模式执行，Python会自动将当前目录加入模块搜索路径：

python -m test.run_files_ee-opt

注意这里不需要加.py后缀，用点号分隔目录和脚本名。

3. 手动在脚本中添加项目根目录到sys.path #

在run_files_ee-opt.py的最开头添加以下代码，强制将项目根目录加入模块搜索路径，这种方法不受运行时工作目录的影响：

import sys
from pathlib import Path

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

# 之后再执行导入操作
from utils.custom_object_functions import create_hollow_room, get_arrow, create_coordinate_axes_mesh

4. 设置PYTHONPATH环境变量 #

在终端运行脚本前，先将项目根目录添加到PYTHONPATH：

Linux/macOS #

export PYTHONPATH=/path/to/your/apx-cv:$PYTHONPATH
python test/run_files_ee-opt.py

Windows（PowerShell） #

$env:PYTHONPATH = "C:\path\to\your\apx-cv;$env:PYTHONPATH"
python test/run_files_ee-opt.py

如果需要永久生效，可以将export命令添加到shell配置文件（如~/.bashrc、~/.zshrc），或者在Windows系统环境变量中添加PYTHONPATH项。

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