Python多文件夹模块导入报错：No module named 'animal'的排查与解决

问题背景 #

文件结构：

- animal // 项目根目录
    - mamal/
        - dog.py
    - reptile/
        - snake.py
    - main.py

dog.py代码：

class Dog:
    def __init__(self):
        self.name = "Dog"

    def draw_dog():
        print("₍ᐢ•ᴥ•ᐢ₎")

main.py代码：

from mamal.dog import Dog

Dog.draw_dog()

运行main.py时出现报错：ModuleNotFoundError: No module named 'animal'

报错原因 #

1. 子目录未被识别为Python包：mamal和reptile目录缺少__init__.py文件，Python默认不会将无该文件的目录视为可导入的模块包。
2. 运行路径错误：若在animal目录内部直接运行main.py，Python模块搜索路径默认不包含animal本身；或在animal目录外使用python animal/main.py的方式运行，都会导致路径层级识别异常。
3. 类方法定义问题：额外提示：draw_dog方法无self参数，直接通过Dog.draw_dog()调用会触发参数缺失报错，属于后续运行会遇到的问题。

解决步骤 #

步骤1：给子目录添加__init__.py文件 #

在mamal和reptile目录下创建空的__init__.py文件，让Python识别它们为合法模块包：

- animal
    - mamal/
        - __init__.py
        - dog.py
    - reptile/
        - __init__.py
        - snake.py
    - main.py

步骤2：选择正确的运行方式 #

方式A：在animal目录外部运行

切换到animal目录的父目录，执行：

python -m animal.main

该方式会将animal目录加入Python模块搜索路径，确保导入层级正确。

方式B：手动添加模块搜索路径

若必须在animal目录内部运行main.py，在文件开头添加以下代码，将项目根目录加入搜索路径：

import sys
import os
sys.path.append(os.path.dirname(os.path.abspath(__file__)))

from mamal.dog import Dog

Dog.draw_dog()

步骤3：修正类方法定义 #

给draw_dog添加@staticmethod装饰器，转为静态方法避免参数报错：

class Dog:
    def __init__(self):
        self.name = "Dog"

    @staticmethod
    def draw_dog():
        print("₍ᐢ•ᴥ•ᐢ₎")

内容的提问来源于stack exchange，提问作者J.C