ModuleNotFoundError: No module named 'xxx.xx'，以及紧随其后的那句'xxx' is not a package，基本是我见过出现频率最高的一对Python报错。不管你是刚写了两周的脚本新手，还是维护过几百个文件的老手，几乎都绕不过这个坑。文件明明就在那里，类也定义好了，一运行就告诉你找不到，这种挫败感很真实。
这篇文章不打算只给结论。我会把Python的导入机制、这俩报错分别触发的条件、不同场景下的正确写法、以及用python -m还是python xxx.py跑代码的区别一次性讲透。最后还有一份完整的排查清单，你以后遇到同类问题，直接照着顺序查，基本能在一分钟内定位。
1. 先搞懂Python导入机制，才知道错在哪
1.1 sys.path才是真正的“搜索名单”
你写import xxx的时候，Python并不是随便在硬盘上翻一翻。它手里有一份固定的“搜索名单”，叫sys.path，是一个字符串列表，里面的每一项都是一个目录路径。Python会严格按照这个列表的顺序，挨个目录去找名叫xxx的文件或文件夹。找到了就用，整个列表翻完还没找到，就抛ModuleNotFoundError。
这个名单里通常包含几类东西：当前脚本所在的目录、环境变量PYTHONPATH指定的目录、Python标准库的路径、以及第三方库所在的site-packages目录。但很多初学者最困惑的一点就是：当前脚本所在目录和你在命令行里敲命令时所在的工作目录不是一回事。举个例子，你在项目根目录敲python subdir/run.py，Python往sys.path里塞的是subdir这个目录，不是项目根目录。你项目根目录里某个包如果只存在于根目录，而此时没有通过任何机制把根目录加进去，那就必然报找不到。
想亲眼看到这份名单，一行命令就能搞定：
python -c "import sys; print(sys.path)"这在后面排查问题时会非常有用。很多看似复杂的导入失败，最终都能归结为一句话：你要导入的东西不在sys.path的任何一个目录里。
1.2 模块与包：引入错误的关键概念
在报错信息里，xxx这条线索指向一个基础概念区分：模块和包。
- 模块：就是一个
.py文件，比如utils.py。 - 包：严格来说，是一个含有
__init__.py文件的目录。但从Python 3.3开始，目录里即使没有__init__.py，也可能被当成所谓的“命名空间包”使用。
当你写import xxx.xx，Python做的其实是两件事。第一步，先找到xxx这个顶层模块或包。第二步，如果在sys.path里找到的第一个xxx是包（也就是目录），Python就去这个目录里继续找xx这个子模块或子包。如果第一步找到的xxx压根不是一个目录，而是一个普通.py文件，那后面的xx就无从谈起了。此时Python会抛出'xxx' is not a package，然后又补一句No module named 'xxx.xx'。
可以这么理解：包是有资格“装”别的东西的容器，而普通模块文件只是单张纸。你想让Python从一张纸里再翻出另一张纸，它当然做不到。后面你会看到，大量报错其实都是在这里翻了车。
1.3 命名空间包和__init__.py的真实关系
网上很多教程说“目录里必须要有__init__.py才能被导入”，这其实已经过时了。Python 3.3之后，目录里没有__init__.py也可以被导入，成为命名空间包。但这带来一个副作用：一个目录能不能被当成包，往往取决于sys.path里搜索到的是不是这个目录本身，以及有没有和它同名的文件抢先被找到。
举个例子，项目里有mypkg目录，但目录里没有__init__.py，同时项目根目录下又躺着一个mypkg.py文件。Python搜索的时候，如果mypkg.py所在目录排在mypkg目录前面，它优先找到的是文件而不是目录，于是mypkg在这里就是一个普通模块，不是包。此时你再写from mypkg import submodule，就会见到那句熟悉的“is not a package”。
所以关于__init__.py，我更建议你的态度是：不管是空文件还是有内容，只要这个目录需要作为包使用，就显式地加上。它相当于给Python一个明确的信号，也杜绝了被同名文件截胡的问题。
2. 两类报错分别出现的真实场景
2.1No module named 'xxx.xx'里的三种情况
这个报错虽然只有一句话，但触发原因至少能分成三类。
第一类是顶层包就找不到。你写的结构是a/b/c.py，然后写了import a.b.c，但sys.path里根本没有包含a所在的目录，于是第一步就挂了。这种问题最常见于脚本放在子目录、又想导入上层项目的某个包。
第二类是子模块名写错。import a.b时，a找到了，但a目录下没有b.py或b目录。可能是文件名拼错，可能是大小写问题，也可能你的a/b/结构里b是多级目录，写成了import a.b而不是import a.b.c。
第三类是目标目录没有作为包被识别。如果a目录缺了__init__.py，同时又被某个同名文件干扰，那么a会被当成模块文件处理，后面的.b自然失败。这种情况经常发生在目录名字太普通的时候，比如项目里有个目录叫utils，另一个文件也叫utils.py，彼此互相打架。
2.2'xxx' is not a package的典型触发方式
这个报错给我的感觉是，“名字找到了，但身份不对”。最常见的触发方式有三种。
其一，xxx.py和xxx/目录同名并存。前面已经说过，Python优先找到.py文件，等你想继续import xxx.xx时，它没法从文件里再找出子模块。
其二，你在一个模块文件内部，试图用包名去导入它自己。比如core.py里写了import core.utils，但core是文件不是目录。或者更隐蔽一点，run.py和run/目录同名，在其它文件里写了import run.some，结果找到的是run.py。
其三，相对导入和绝对导入混用导致的概念错位。比如你本来处在包内部，应该用相对导入from . import utils，结果写成了from mypkg import utils。此时Python也会尝试把mypkg当作一个包来处理，但如果mypkg在sys.path里对应着当前的模块文件，麻烦就来了。
2.3 本地文件与第三方库的“撞名”灾难
除了自己的代码内部出问题，还有一类场景非常隐蔽：你本地定义的包，和site-packages里某个第三方库同名。
比如你装了一个叫requests的第三方库，但你的项目里恰好也有一个requests.py文件，或者一个requests/目录。Python在sys.path中的搜索顺序里，通常本地目录排在第三方库目录之前。于是你每次import requests，导入的都不是官方库，而是你的本地文件。如果本地文件里没有你需要的那个子模块，No module named 'requests.xxx'就出现了。
我见过最离谱的一次，是把math.py放在项目根目录，然后整个项目里所有用到import math; math.sqrt()的地方全部炸掉，因为导入的是那个只有几行代码的本地文件。这种“撞名”排查起来极其费神，但一旦知道了原理，定位就很快。处理方法就是在项目里保持警惕，不要用标准库名、热门第三方库名来给自己的文件命名。
3. 从根上解决：改造项目结构和导入方式
3.1 应急方案：手动把路径加进sys.path
有人习惯在脚本开头直接改sys.path，这当然能救急。比如你的项目结构是这样：
project_root/ ├── main.py ├── mypkg/ │ ├── __init__.py │ └── core.py如果main.py在根目录，而mypkg也在根目录，直接import mypkg.core一般没问题。但如果main.py跑在子目录里，比如：
project_root/ ├── scripts/ │ └── main.py └── mypkg/ ├── __init__.py └── core.py在scripts/main.py里直接import mypkg就不行了，因为sys.path[0]是scripts目录，而不是project_root。这时候常见的土办法是：
import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).resolve().parent.parent))这段代码的意思是：自己算一下当前文件在哪，然后取它上两级的目录（也就是project_root），把它插到sys.path的最前面。之后import mypkg就能成功。
但这方式我不建议长期用。原因有两个：第一，每次都要计算相对路径，项目结构一调整，这段代码也要跟着改，维护成本不小。第二，它绕过了Python包管理的正常机制，别人接手你的代码时，很难一眼看出项目的入口和依赖关系。
3.2 正规方案：把项目打包，一劳永逸
更推荐的做法是，从一开始就把项目当成一个可安装的包来设计，也就是“src layout”。一个相对标准的结构长这样：
project_root/ ├── pyproject.toml └── src/ └── mypkg/ ├── __init__.py ├── core.py └── cli.py然后在pyproject.toml里写一份最基本的构建配置：
[build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my-pkg" version = "0.1.0" [tool.setuptools.packages.find] where = ["src"]之后在project_root目录下执行：
pip install -e .-e表示可编辑安装，也就是说你改src/mypkg里的代码，不需要重新安装，导入时就会自动生效。完成之后，不管你当前工作目录在哪，不管你写脚本的位置在哪，都可以直接：
import mypkg.core因为在可编辑安装时，setuptools已经通过.pth文件把src目录的路径加到了site-packages的环境里，而mypkg也变成了一个正式注册的包。这是目前Python社区最推荐的解决导入问题的方式之一，因为它从根本上绕开了“依靠当前目录能不能找到”的随机性。
3.3__init__.py到底该放哪些东西
__init__.py可以完全为空，但空文件和精心设计的__init__.py差别很大。我的习惯是：第一，保证它存在，把目录标记成常规包；第二，如果包有对外核心API，可以在__init__.py里做一次“汇总导出”。
比如：
# mypkg/__init__.py from .core import main_func from .cli import run __all__ = ["main_func", "run"]这样做的好处是，使用者可以写from mypkg import main_func，而不必关心main_func到底定义在core.py还是别的文件里。对于团队协作的项目，这相当于给包画了一个稳定的对外边界。但它也有副作用：如果core.py依赖某个第三方库，而该库没有安装，那么单单import mypkg就会报错，因为你从一开始就触发了所有汇总导入。
所以在__init__.py里导入内容，需要克制，只导出确实稳定、轻量的模块。改动频繁、依赖复杂的模块，让使用者自己用from mypkg.core import thing按需引入更安全。
4.python xxx.py和python -m xxx差别巨大
4.1 两种运行方式下sys.path[0]完全不同
很多导入问题不是代码写错了，而是“运行方式”用错了。这一点经常被忽略。
你执行python scripts/main.py时，Python把scripts目录作为sys.path的第一个元素。你想导入兄弟目录的东西？找不到。你想从项目根目录导入某个包？也找不到，除非根目录恰好也在搜索路径里。
但你执行python -m scripts.main时，Python的行为完全不同。它首先把当前工作目录加到sys.path[0]，然后才按照模块名去搜索并执行对应文件。所以你在项目根目录执行python -m scripts.main，import mypkg就能直接成功，因为根目录已经进了搜索路径。
同样一份代码，换一个运行命令，结果可能天差地别。很多开发者说“我在IDE里运行没问题，命令行就不行”，核心原因就出在这里——IDE通常会自动把项目根目录加到sys.path里，而命令行并不会。
4.2-m和相对导入的配合原理
再往深一层说，python -m不仅仅是改了路径，它还影响相对导入的可用性。
假设你的包结构里有一个模块：
# src/mypkg/core.py def helper(): print("helper")另一个模块要引用它：
# src/mypkg/main.py from .core import helper if __name__ == "__main__": helper()如果你直接执行python src/mypkg/main.py，Python会报一个错：ImportError: attempted relative import with no known parent package。原因很简单：当你以脚本方式直接运行一个文件时，这个文件的__package__是空的，它不认为自己属于任何一个包，于是.开头的相对导入就失去了参照物。
但如果你从src目录的上级执行：
python -m mypkg.mainPython把src加进sys.path[0]，然后按mypkg.main这个模块名找到文件并执行。此时__package__会被正确设置成mypkg，文件内部的from .core import helper就能顺利工作。
这是Python官方推荐的多文件工程运行方式。只要你把项目组织成包结构，并且在包目录里设计好入口模块，统一用python -m来启动，大部分导入问题根本不会出现。
4.3 给包加一个__main__.py，让整个包可以直接运行
如果你希望执行python -m mypkg就能直接启动整个包，而不是每次都要敲python -m mypkg.main，可以在包里放一个固定名称的入口文件：__main__.py。
src/mypkg/ ├── __init__.py ├── __main__.py ├── core.py └── cli.py# src/mypkg/__main__.py from .cli import run if __name__ == "__main__": run()当python -m mypkg执行时，Python会在包内部找__main__.py并运行它。这是给包提供标准CLI入口的通用做法，很多命令行工具类项目都采用这个结构。这样既保持了包内模块的相对导入关系，又让使用者只需要记住一个包名，不用关心内部文件结构。
5. 实战排查清单与修复速查表
5.1 从报错信息倒推排查步骤
遇到导入类报错，我的排查顺序基本是固定的，照着做可以避免瞎试。
第一步，把完整的堆栈信息打开，定位第一行报错发生在哪个文件哪一行。重点看是哪个import语句触发的，以及引用的是xxx.xx还是单独的xxx。这决定了问题发生在顶层模块，还是发生在子模块。
第二步，打印当前运行环境的sys.path，确认你的项目目录是否在其中。这一步能快速排除“路径根本没加进去”的情况。
第三步，确认你要导入的那个路径，在磁盘上实际是什么形态。用文件管理器或命令行看一眼，是xxx.py文件，还是xxx/目录，目录里有没有对应的xx.py。很多时候单纯是文件结构问题和预期不符。
第四步，搜索项目里有没有同名但不同类型的实体。比如xxx.py和xxx/目录并存，或者在某个地方定义了一个叫xxx的变量、函数，遮蔽了模块名。
第五步，检查运行方式。你是用python xxx.py还是python -m xxx？当前工作目录在哪里？尝试把运行方式统一成python -m往往能立刻见到效果。
第六步，确认解释器环境。在命令行执行python -c "import sys; print(sys.executable)"，看看你用的到底是不是当前虚拟环境里的Python。很多人装了库，却发现pip install装进了A环境，运行用的是B环境，这种情况排查多久都是白费。
5.2 常见症状对照表
| 报错/现象 | 常见原因 | 推荐处理 |
|---|---|---|
No module named 'xxx' | 顶层模块不在sys.path | 用python -m运行，或把项目根目录加入PYTHONPATH，或安装为包 |
No module named 'xxx.xx' | 顶层xxx找到了，但内部没有xx | 检查xxx目录内是否有xx.py/xx子包，文件名是否拼错 |
'xxx' is not a package | 找到的是同名.py文件而不是目录 | 删除同名文件，或给目录加上__init__.py |
| 相对导入直接运行时报错 | __package__为空 | 改用python -m方式运行 |
| IDE能跑，命令行报错 | IDE自动添加了根路径，命令行没有 | 统一用python -m，或配置PYTHONPATH |
已经pip install了但找不到 | 解释器/虚拟环境不一致 | python -m pip install，确保安装进当前环境 |
| 导入后拿到了错误的对象 | 与标准库或第三方库同名冲突 | 重命名本地文件或包，避免撞名 |
5.3 定位“到底导入了哪个文件”的快捷命令
怀疑导入路径不对时，一个很有用的命令是查看模块实际对应的文件路径：
python -c "import mypkg; print(mypkg.__file__)"如果打印出来的路径根本不是你想用的那个目录，说明搜索顺序出了问题，要么有同名干扰，要么sys.path顺序不对。这个命令在排查“奇怪行为”时候格外有效，因为它直接告诉你Python眼中的真相。
同样地，如果你想确认某个包是不是可编辑安装状态，可以打印：
python -c "import mypkg; print(mypkg.__path__)"__path__会列出包的搜索路径。如果指向的是src/mypkg，说明基本没装错。
6. 项目结构的习惯建议与避坑心得
6.1 从第一天就按“包”思想组织代码
哪怕你只是在做一个几十行的小Demo，我也建议在创建目录结构时就把“包”和“模块”的概念落实下来。最简单的方式是：把主要功能放在一个包目录下，包目录里放__init__.py，然后写一个独立的、薄薄的入口脚本，用python -m去调用它。不要把所有脚本文件平铺在同一个目录里，也不要出现包名和文件名互相纠缠的混乱结构。
这样做最大的价值并不是第一次运行就一定能成功，而是让你的项目天然具备“可以被工具化”的基础。等到你想给脚本写单元测试、做命令行工具、发布到内部私有库时，包结构已经摆好了，不需要再经历一次重构。
6.2 命名的“玄学”：这不是小事
命名比你想象中更重要。用utils.py、helper.py、tools.py这类名字确实让代码看起来简洁，但一旦多人协作、多模块代码同时存在，这些名字太容易撞。我自己的规矩是：项目内部包的命名要带上项目前缀或者业务含义，比如project_xxx_data或者xxx_api_client，尽量不要用一个通用词。
还有就是避免和标准库、正在使用的第三方库重名。你可以建立一个简单的项目内约定：任何文件名和包名，先在当前环境中查一下是否已有同名已安装模块。一个小技巧就够用：
pip list | grep <name>或者在项目全局搜索同名的.py文件。多花十秒钟，能省掉后面一天的排查时间。
6.3 关于from xxx import *的一点建议
from xxx import *这种写法会导入xxx模块里所有不以下划线开头的名称。如果xxx包很大，或者模块内部有大量中间变量，很容易把命名空间搞乱，更糟糕的是可能意外覆盖你已经定义好的函数。如果你在官网见到某模块写了__all__，那还稍微可控一点；没有__all__的话，import *的结果基本上是“全给你塞进来”。
所以我更建议只导入你真正需要的内容。比如from mypkg.core import main_func，明确、清晰、可追踪。一旦以后排查问题，任何一个名字都能顺着import语句精确找到出处。
6.4 我的最终建议
如果你只能记住一条，那我建议你记住：高频率使用python -m去运行你的包内模块，而不是python 某文件.py。这是我在处理了不知道多少次导入问题之后，最想让你提前知道的东西。它解决的不只是报错，更是让你的项目从一开始就走在整洁、可维护的路上。真正理解了sys.path、包和模块的区别、绝对导入和相对导入各自适用的场景，你会发现这类报错其实只需要两分钟就能定位清楚。
以后再碰上ModuleNotFoundError，别慌，先看一眼sys.path，再确认目标实体的形态，最后检查运行命令。三步下来，问题基本就跑不掉了。
