Python项目“No module named 'Shapes'”导入错误的解决方案咨询

项目结构 #

C:.
├───Shapes
│   │   Circle.py
│   │   Rectangle.py
│   │   Shape.py
│   │   __init__.py
│           
├───tests
│   │   conftest.py
│   │   test_circle.py
│   │   test_rectangle.py

问题描述 #

• 直接运行Circle.py或Rectangle.py时，报错No module named 'Shapes'
• 在tests目录下执行测试时，报错ModuleNotFoundError: No module named 'Shapes'

相关代码示例：

Circle.py #

from Shapes.Shape import Shape  # Importing the Shape base class
import math as Math
...（其余代码）

Rectangle.py #

from Shapes.Shape import Shape  # Importing the Shape base class
...（其余代码）

test_circle.py #

import pytest
from Shapes.Circle import Circle
...（其余代码）

test_rectangle.py #

import pytest
from Shapes.Rectangle import Rectangle
...（其余代码）

已尝试的方法 #

• 在测试文件中手动添加项目根目录到sys.path，但并非最佳实践
• 使用相对导入，却触发ImportError: attempted relative import with no known parent package错误

解决方案 #

1. 修复脚本运行的导入错误 #

方法一：用模块方式运行脚本

从项目根目录执行命令，不要直接运行Circle.py或Rectangle.py文件：

# 运行Circle模块
python -m Shapes.Circle
# 运行Rectangle模块
python -m Shapes.Rectangle

这种方式会自动将项目根目录加入Python的模块搜索路径，原生支持绝对导入。

方法二：改用相对导入（配合模块运行）

修改Circle.py和Rectangle.py中的导入语句为相对导入：

# Circle.py 改为
from .Shape import Shape
import math as Math
...

# Rectangle.py 改为
from .Shape import Shape
...

修改后依然需要从项目根目录用python -m Shapes.Circle方式运行，不能直接双击或单独执行该文件。

2. 修复测试运行的导入错误 #

直接从项目根目录运行pytest命令：

python -m pytest tests/ -v

这种方式会让pytest自动将项目根目录纳入模块搜索路径，测试文件中的绝对导入from Shapes.Circle import Circle就能正常工作，无需修改测试代码。

推荐的项目组织与导入方式 #

• 保持现有包结构：Shapes作为一个完整的Python包（保留__init__.py），包内部模块间使用相对导入（比如from .Shape import Shape），外部代码（如测试、其他项目）使用绝对导入（比如from Shapes.Circle import Circle）。
• 优先使用python -m 包名.模块名的方式运行脚本，避免直接执行单个.py文件，这是Python官方推荐的包模块运行方式。
• 规范项目结构：在项目根目录添加pyproject.toml或setup.py，将项目安装为可编辑模式：

  pip install -e .
  

  安装后，无论在系统哪个路径下，都能直接导入Shapes包，彻底解决模块搜索路径问题。

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