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.pyPython往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.xxPython做的其实是两件事。第一步先找到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.2xxx 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 [setuptools61.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.mainimport 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.pyPython会报一个错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再确认目标实体的形态最后检查运行命令。三步下来问题基本就跑不掉了。