一个很有意思的现象Python学到一定阶段很多人会卡在“包”这个概念上。网上搜“python中的包”绝大多数教程只会告诉你一句话包就是一个包含__init__.py文件的目录。但等你真正开始管一个像样点的项目或者第一次试图把自己写的东西安装进系统环境时会立刻发现这句话远远不够用。import 还是报错模块还是找不到明明代码在本地跑得飞快换一台机器就束手无策。这篇东西想做的不是再把“包是目录”这个知识点复述一遍而是把“包”的完整链条讲清楚前半段是包在 Python 导入系统里如何被解析、如何工作后半段是包如何被打包、安装成为可以被别人import的代码。这两条线打通了你写小工具、拆大项目、发布自用库时思路都会清晰很多。适合刚入门想进阶的同学也适合那些已经把 Python 用了很久、但一遇到ModuleNotFoundError就只能网上搜报错的人。1. “包”其实有两个身份目录命名空间与发布单元1.1 导入系统眼中的包一个可以“点号加载”的命名空间从 Python 解释器的角度看包本质上还是模块只不过这个模块对应的是一个目录而不是一个.py文件。当你写下import myapp.core解释器做的事可以拆成三步在sys.path记录的路径列表里按顺序找myapp这个名字找到一个名叫myapp的目录或模块文件后把它加载为一个模块对象并继续查找目录内的core最终把myapp.core这个子模块也加载进来缓存到sys.modules里。目录到底算不算一个包传统上靠__init__.py来判断。只要一个目录里有这个文件它就能被当作常规包导入没有这个文件在 Python 3.3 之后如果条件满足它也可以作为“命名空间包”存在只是行为上有些差异。这个差异后面会专门展开。模块和包在运行时还有一个很直观的区分常规包对象拥有__path__属性它是一个列表告诉解释器“应当到哪些路径下面去找我的子模块”普通模块则没有这个属性。你可以自己验证一下import json print(type(json)) # class module print(hasattr(json, __path__)) # Falsejson.py 是模块 import urllib print(type(urllib)) # class module print(hasattr(urllib, __path__)) # Trueurllib 是包这个区别看起来不起眼但它决定了递归查找能否继续进行。目录里有__path__解释器才能一层层往深处找没有这个属性子模块就无法再被定位。1.2 分发工具眼中的包一个可以被安装的发布单元日常口语里说的“安装一个包”其实说的是另一个层面的东西。pip install xxx安装的并不一定是一个目录包它可以是单个模块文件也可以是一堆散落的文件甚至可以是一个压缩包。只要这些内容被正确地打包并且包含描述性的元数据它就是一个“发布单元”。发布单元和前面说的“目录包”并不是一一对应的。现实中常常出现这种情况你明明看到site-packages里有一个叫myapp的目录import 也成功了但你后来修改了myapp源码程序却依然使用旧的逻辑。原因是你改的是工作区里的myapp目录而解释器加载的却是site-packages里那个安装版本。如果意识不到这两者不是一回事排查这种“改了没生效”的问题会非常痛苦。下面这张表可以直接帮你对照自己遇到问题时该从哪一层入手概念物理形态作用层面典型检查手段模块单个.py文件导入系统module.__file__常规包含__init__.py的目录导入系统package.__path__命名空间包不含__init__.py的目录导入系统查看sys.path的多段路径发布单元wheel 文件、sdist 压缩包安装与分发查看包索引下载记录、dist-info目录1.3 为什么要先把身份分清楚很多初学者一上来就想知道“包怎么写”我觉得第一件事反而应该是搞清楚“包在哪一层出了问题”。举个例子有人把一个目录压缩发给同事同事解压后import失败。这通常不是包目录结构有问题而是同事的sys.path里根本没有包含这个目录的上一层路径。这时候你要思考的是导入系统那一层。另一种场景你写了一个小库用pip install -e .以可编辑模式装好之后每次改代码都能即时生效。但如果哪天你换成了普通安装方式site-packages里就会拷贝一份快照。这时候如果再改源码程序不会跟着变。你面对的是发布单元那一层的问题。2. 一个目录如何成为真正的包__init__.py的职责边界2.1 最朴素的包结构随手建一个包只需要这样myapp/ __init__.py core.py utils.py__init__.py哪怕完全是空文件也足以让myapp变成可以导入的包。于是你可以写import myapp.core来加载子模块。但实际项目中空__init__.py其实挺浪费的。它有三个常见用途值得按需使用第一导出对外 API。你不想让用户记住myapp.core.service.Client这么长的路径可以在__init__.py里写from .core.service import Client这样用户只需要from myapp import Client。这种做法本质上是给包做了一次“门面整理”把内部模块路径隐藏起来以后内部结构调整时对外接口还能保持稳定。第二做导入时的初始化。有些包希望被 import 时自动加载配置、检查环境变量或注册插件这些逻辑可以放在__init__.py里。但这里必须克制。一个常见的反例是__init__.py里 import 了某个模块那个模块反过来又从__init__.py里取某个变量结果就是循环导入。这里的原则是__init__.py尽量只做轻量整理重的初始化逻辑放到显式调用的函数里。第三放元数据。很多人习惯在__init__.py里写__version__ 0.1.0。它能跑通但有个隐患如果包内部某个模块也需要读取版本号而它用了from myapp import __version__在包初始化过程中就可能产生循环依赖。更稳妥的做法是单独建一个_version.py文件例如# myapp/_version.py __version__ 0.1.0然后在__init__.py里from ._version import __version__。这样版本信息只属于一个底层模块不会因为初始化顺序被“卡住”。2.2 不要神话__all____all__是另一个经常被误解的变量。它只影响一种写法from myapp import *。也就是说__all__可以看作你允许被“星号导入”冲刷出去的名字清单。它不会限制import myapp.core不会禁止别人写myapp.core.func()更不是“模块白名单”。# myapp/__init__.py __all__ [Client, config]这份清单写清楚之后别人使用from myapp import *时只会拿到Client和config。这样做对 API 设计有好处至少你明确告诉使用者“公开面”是什么避免不小心把内部工具函数也暴露出去。2.3 没有__init__.py的命名空间包Python 3.3 起目录里没有__init__.py也可能被当作包导入它叫命名空间包。机制可以这样理解假设sys.path里同时有/opt/a和/opt/b两个目录而/opt/a/plugins和/opt/b/plugins都没有__init__.py那么plugins会成为一个“合并起来”的命名空间包。此时import plugins.alpha和import plugins.beta可以分别从不同物理路径加载。这个特性对插件系统很有价值比如不同团队各自维护一个插件目录最终通过路径配置合并成一个统一的命名空间。但如果是在一个普通业务项目里我建议把它当“进阶知识”看待不要一上来就用。原因很简单没有__init__.py的包对于很多工具和调试手段来说并不透明文件一多你很难判断某个子模块到底来自哪个目录。3. import 搜索路径与相对导入最常见的报错根因其实都在这3.1 解释器到底去哪里找包一个包能不能被导入不取决于你“当前在哪个目录下”而取决于包含这个包的那一层目录是否在sys.path里。sys.path一般由三部分构成脚本所在目录或交互模式下当前工作目录PYTHONPATH环境变量里配置的路径Python 安装目录内置的site-packages。很多人把项目结构写成这样project/ myapp/ __init__.py core.py然后在project目录下运行python myapp/core.py。这个脚本的sys.path[0]是project/myapp这个目录而不是project。所以解释器根本不知道外面还有一层myapp包import myapp.utils自然失败。你要么在project目录下用python -m myapp.core启动要么在代码里临时把project加进sys.path。这里我强烈建议用-m方式而不是到处拼sys.path。python -m myapp.core会把当前工作目录放入sys.path并且以模块的形式执行myapp/core.py整个包上下文能正确建立内部模块之间互相导入也非常顺畅。3.2 绝对导入与相对导入分别什么时候用包内部模块之间的导入有两种写法。绝对导入是from myapp.core import Client相对导入是from .core import Client from ..utils import helper相对导入里的.表示当前包..表示上层包。它的最大好处是不管你的包最终叫myapp还是被改名成my_service内部互相引用都不受影响。但相对导入有一个硬性触发条件当前模块必须处于一个包上下文里也就是 Python 得知道你属于哪个包。如果你直接执行一个包内的.py文件比如python myapp/core.py解释器把core.py当作顶层脚本运行它没有任何“父包”这时候写from . import utils就会看到那条极经典的报错ImportError: attempted relative import with no known parent package复现路径非常简单随便建一个包在包内模块里写相对导入然后直接运行该模块文件。修复方式前面已经提过退到包的外层目录用python -m 包名.模块名启动。3.3python -m为什么会管用理解-m的机制有助于把这类问题一次根治。python -m myapp.core做的事情是把myapp.core作为一个非顶层模块来执行同时 Python 会为这个模块设置正确的__package__属性。有了这个属性相对导入才能计算出“当前包是哪个、向上找几层”。直接运行脚本文件时__package__为空字符串相对导入自然无处安放。如果你开发的是一个带入口命令的小项目建议在包里加一个__main__.pymyapp/ __init__.py __main__.py这样使用者可以执行python -m myapp包会以“主程序”方式运行。这个过程同样处于包上下文里模块间的相对导入不会踩坑。实际工作中我给很多项目补上__main__.py之后测试和排错都轻松很多。4. 把一个目录包变成可安装的发布单元pyproject.toml 构建全流程4.1 为什么现在都推荐 pyproject.toml老项目里常见setup.py它的确能完成打包但setup.py是可执行代码打包前往往会先执行它引入了不少潜在问题。现在更通用的做法是用pyproject.toml这种声明式配置它把构建系统、项目元数据、依赖信息都集中在一个文件里。Python 包管理器对它的支持已经很成熟新建项目时我更推荐直接从这个文件开始。一个带src布局的最小项目长这样my_awesome_lib/ pyproject.toml src/ my_awesome_lib/ __init__.py core.py tests/ test_core.pysrc布局的好处是你开发阶段的sys.path不会直接把包目录本身暴露进去能避免“本地能 import、安装后却不行”的经典尴尬。4.2 一份能跑通的最小配置打开pyproject.toml写入如下内容[build-system] requires [setuptools61] build-backend setuptools.build_meta [project] name my-awesome-lib version 0.1.0 description A small library to demonstrate package building requires-python 3.9 dependencies [] [project.scripts] awesome-demo my_awesome_lib.core:main [tool.setuptools.packages.find] where [src]几个字段简单解释一下[build-system]描述用什么工具来构建包。requires里列的是构建期间需要安装的依赖build-backend决定构建入口。[project]是项目元数据所在name是发布名version是版本号dependencies是运行时依赖列表。[project.scripts]用来生成命令行入口。awesome-demo my_awesome_lib.core:main表示安装包之后会在可执行路径里生成一个awesome-demo命令运行它时会导入core模块并调用main()。[tool.setuptools.packages.find]告诉构建工具到src目录下自动发现包。假设src/my_awesome_lib/core.py里有一个简单函数然后在项目根目录执行python -m pip install -e .-e是可编辑安装本质上是在环境中生成一个入口文件让它直接指向你的源码目录。这样你每次改源码无需重新安装import 总能拿到最新代码。开发阶段强烈推荐这么做。4.3 构建出可分发的文件开发阶段跑通后如果要给别人用就得构建发布文件。需要提前安装一个构建工具python -m pip install build python -m build执行完会在dist/下生成两个文件.whl是预编译好、可直接安装的格式.tar.gz是源代码包适合在无法直接安装 wheel 的场景下使用。构建之后再检查一下 wheel 里到底进了哪些文件这一步很多人容易忽略但非常值得做unzip -l dist/my_awesome_lib-0.1.0-py3-none-any.whl如果发现某些目录没被包含比如新加的子包没有进去通常是packages.find的配置问题需要回去核对where和include设置。4.4 发布前我建议你做的四项检查第一在全新虚拟环境里安装构建产物避免“我本地能用”的假象。第二确认pyproject.toml里没有在正式包中暴露多余文件比如测试目录。第三版本号要有明确策略0.1.0、0.2.0这种三段式版本比随手写的1.0更便于日后维护依赖关系。第四如果有资源文件比如 JSON 配置或模板需要在[tool.setuptools.package-data]里明确声明否则构建时不会自动包含。如果你打算把包传到公共包索引或者公司内部的私有仓库基本也是走这条构建流程区别只是最终上传到的仓库地址不同。在自动化构建流程中通常还会加上 CI 检查确保每次发版都从干净环境构建。5. 安装成功但 import 失败那些反复出现的典型坑5.1 装到了别的环境里这个问题出现的频率远超想象。很多人会先激活虚拟环境然后顺手执行pip install结果发现装到了系统级 Python 里。最直接的排查方式是打印当前解释器路径和包的实际位置python -c import sys; print(sys.executable) python -c import my_awesome_lib; print(my_awesome_lib.__file__)统一用python -m pip install而不是裸pip install能很大程度上减少这类事故因为前者和当前解释器一定是绑定的。5.2 文件根本没被打进发布包这种情况最隐蔽。你在源码目录里加了一个subpkg/子目录本地开发时因为源码路径就在sys.path里import 一切正常。等别人安装whl文件后却找不到subpkg因为构建时packages.find并没有识别到它。遇到这种问题用上一步的unzip -l检查 wheel 内容往往一眼就能发现。如果项目里新增了子包但没更新find配置可以在[tool.setuptools.packages.find]中显式使用include参数[tool.setuptools.packages.find] where [src] include [my_awesome_lib*]include里的星号会匹配主包下面所有子包比逐个列举省心得多。5.3 路径上残留了同名旧文件我见过不少案例项目的src目录改成了myapp但旧的myapp.py文件一直留在工作目录里。当程序在某个目录下运行时sys.path把当前目录排在最前于是解释器优先加载了那个旧模块。结果新功能死活不生效print(module.__file__)一查发现加载的路径根本不是你以为的那个。这个坑的排查思路非常简单遇到任何“改了源码但行为不变”的情况先打印包名.__file__确认它从哪个位置加载。如果发现是旧文件直接删除或重命名。5.4 循环导入与初始化顺序循环导入一般发生在包变大之后。一个典型场景是__init__.py里 import 了core而core里又反过来from mypackage import some_flag。Python 加载mypackage时__init__.py刚执行到一半some_flag还没定义于是报出ImportError: cannot import name some_flag。这类问题往往不是语法错误而是模块初始化顺序设计得不够清晰。我的处理原则是把共享的基础工具放到独立的base.py或_compat.py里让底层模块不依赖包顶层的出口变量确实需要互相引用的可以在函数内部延迟导入也就是用到时再import避免模块加载阶段发生交叉依赖。5.5 资源文件读取路径错误最后这个坑几乎每个用过“带配置文件的包”的人都会遇到。在包里写open(data.json)去读资源本地跑得好好的但当你把包安装到其他环境、从其他目录调用时程序却报FileNotFoundError。原因很简单相对路径是相对于当前工作目录的而不是相对于包文件所在目录。正确的做法是围绕包文件的位置来定位资源from pathlib import Path DATA_FILE Path(__file__).parent / data.json如果是库代码更推荐用标准库importlib.resources相关的 API 来访问包内文件它对安装包和打包后的场景处理得更好。一句话总结永远不要把资源路径寄托在“调用者当前在哪个目录下”这件事上。最后再分享一点个人体会如果只能给一条建议我会说不要急着追求复杂的工程结构先从一个几十行的小工具开始把它拆成core.py、utils.py两个模块放到一个带__init__.py的目录里用python -m方式运行再顺手做成可安装包。这个过程看似简单但整套“导入、打包、安装”的概念会自然串起来。之后再面对大型项目的包结构你就不是靠背结论而是真正理解了解释器每一步在做什么。还有一个小技巧值得养成习惯只要写了包就第一时间在包目录外层执行python -m myapp确认它能以包上下文方式运行。有了这个入口后续所有相对导入问题都会在早期暴露而不是等到项目跑起来才手忙脚乱地排查。包这个东西说穿了就是一个命名空间加上一套规范的搬运流程搞懂了它就不再是玄学。