PyCharm打包whl全流程：从项目结构到pip安装实战

你是不是也遇到过这种场景在PyCharm里写了一个小工具库自己用着很顺手同事问你要源码自己跑。你把整个项目文件夹发过去对方光配环境就要折腾半天或者发一个压缩包里面虽然什么都有但收件人根本不知道先执行哪一个文件。我第一次给别人发工具的时候就是第二种做法发完还要远程指导对方装依赖、配目录、改默认路径折腾了整整一个下午。后来我把项目打成了whl文件对方一句pip install mytool-1.0.0-py3-none-any.whl就装好了import、调用、卸载都交给pip管理再没出过岔子。这篇文章就来聊聊在PyCharm里把一个Python项目打包成whl的完整流程。内容包括什么是whl、打包前项目结构怎么设计、setup.py和pyproject.toml怎么配、PyCharm里三种实际可用的打包操作方式以及我在实践中踩过的坑和排查思路。不管你是想把自用工具发给同事还是准备做团队内部的依赖分发这篇文章应该都能帮你省不少时间。提前说一句PyCharm的社区版就完全够用下面的所有操作我都在社区版上验证过不需要任何额外付费功能。1. 先搞清楚为什么要打成whl它解决了什么1.1 whl和源码压缩包的本质区别很多人对whl的理解停留在一种安装包格式但对它到底解决了什么并不清楚。简单说wheel是Python官方推荐的二进制分发格式它在PEP 427里被正式定义和传统源码包最大的区别是wheel在安装时不需要再执行setup.py构建过程pip把文件解压到site-packages就算装完了速度极快而且能明确声明依赖、入口点和平台兼容范围。拿发zip类比压缩包像是把食材和菜谱一起塞给朋友他得自己开火、调味、掌握火候而whl像是端上一盘做好的菜直接开吃——什么依赖、目录结构、入口脚本安装时全部分配妥当。对收包的人来说唯一的动作是pip install xxx.whl然后就能import xxx。我自己判断该不该打成whl有一个很简单的标准只要你的代码写成了可以被import的形态不管是给项目内部用还是给人分发都值得打成whl。反过来如果只是几个零散的脚本互相不引用那直接发源码就行不必硬套包管理这套。1.2 什么样的项目适合打成whl一个合格的whl包通常具备这几个特征有明确的包名称和版本号有稳定的对外接口也就是别人import之后能用的公开函数/类依赖项清晰并且没有和项目根目录绑死的路径假设。比如你写了一个日志清洗工具内部有log_cleaner/core.py、log_cleaner/formatters.py对外提供log_cleaner.clean(file_path)这样的入口这就非常适合打包。但如果你的项目是一个Django网站、一个桌面应用或者一个必须要靠命令行启动的完整产品whl只适合作为其中的一个依赖组件不适合把整个应用装成whl分发。桌面应用要打包成exe或用PyInstaller处理服务端要打成Docker镜像那又是另一套流程了。另外有读者会问我的包发给同事用和上传到公司私有源有什么区别本质上没有区别whl只是一个文件既可以微信发送、放到共享盘也可以传到nexus、devpi这类私有制品仓库里配合pip的--index-url参数就能用公司源直接安装。这部分我放到后面分发节里细说。2. 打包前的项目结构设计与环境准备2.1 标准项目目录应该怎么搭打包这件事80%的成功率取决于你项目结构够不够标准。如果你现在还是把所有py文件平铺在项目根目录下连一个__init__.py都没有那打包大概率会失败或者打出来也是个半残品。一个最基础的、可以成功打成whl的目录长这样mytool/ ├── mytool/ │ ├── __init__.py │ ├── core.py │ └── utils.py ├── tests/ │ └── test_core.py ├── README.md ├── LICENSE ├── setup.py └── pyproject.toml注意看外面那层mytool/是整个项目根目录里面那层mytool/才是真正的Python包二者同名经常让人混淆但这是Python社区的约定俗成你进入项目根目录看到的第一层目录就是可导入的包目录。每个包目录下必须有__init__.py文件这是Python识别这是一个包的标志没有它find_packages()根本找不到你的模块。这里有一个我强烈推荐的细节如果你不是在做已经成型的老项目新项目尽量采用src布局也就是把所有包代码都放在一个src/目录里mytool/ ├── src/ │ └── mytool/ │ ├── __init__.py │ └── core.py ├── tests/ ├── setup.py └── pyproject.tomlsrc布局的好处是你在项目根目录跑测试或写示例代码时不会意外import到本地源码而把bug掩盖掉——你导入的是真正安装后的包。坏处是配置时要在setup.py和pyproject.toml里多写一个wheresrc参数。对新手来说平铺布局更简单直观也完全能打包我建议先跑通平铺布局再决定要不要切src。2.2 在PyCharm里准备虚拟环境打包环境的第一条铁律所有打包工具都装在这个项目专用的虚拟环境里不要用全局解释器。全局环境里装了一套乱七八糟的包你setup.py里写的install_requires可能照搬了全局环境里碰巧能跑的版本打出的包在干净环境里一装就暴露问题了。在PyCharm里操作很简单。打开右下角Python解释器设置点击Add New Interpreter - Virtualenv Environment选一个干净的Python版本比如3.8或3.10创建即可。创建完成后打开Terminal面板你会看到命令行提示符前面带上了(venv)这就说明你已经在这个虚拟环境里了。如果Terminal里没出现(venv)说明PyCharm没有自动激活当前项目的虚拟环境。Windows下手动激活是venv\Scripts\activatemacOS和Linux下是source venv/bin/activate激活之后先安装打包工具链。基础三件套setuptools、wheel、build。pip install --upgrade pip setuptools wheel build为什么要装build原因后面讲命令的时候细说这里先记住它是官方推荐的构建前端工具。3. setup.py和pyproject.toml核心配置详解3.1 setup.py的6个关键参数说到打包配置绕不开setup.py。虽然新项目都在迁移到pyproject.toml但网上大量老教程、开源项目里还是setup.py你得能看懂它。一个能直接抄的setup.py长这样# -*- coding: utf-8 -*- from setuptools import setup, find_packages setup( namemytool, version1.0.0, description用于清洗和分析日志的工具库, long_descriptionopen(README.md, encodingutf-8).read(), long_description_content_typetext/markdown, authorYour Name, author_emailyouexample.com, licenseMIT, packagesfind_packages(), include_package_dataTrue, install_requires[ requests2.20, pandas1.0, ], python_requires3.7, classifiers[ Programming Language :: Python :: 3, Operating System :: OS Independent, ], )这里面最重要的几个点我一个个说。name和version是pip用来唯一识别包的元数据name不能有大写字母、不能有空格建议全小写用下划线或短横线。version不是随便写的建议遵循语义化版本号“主版本号.次版本号.修订号”比如1.0.0。你每次改代码重新打包前都应该先更新version否则后面安装时pip会认为版本没变不覆盖安装排查问题的时候很迷惑。packagesfind_packages()是自动发现项目里所有带__init__.py的目录把它们作为包内容打包。如果你的代码用了src布局这里要改成find_packages(wheresrc)另外还得告诉setuptools去哪个目录找包对应的写法是package_dir{: src}。install_requires声明运行时依赖。有个常见的反模式是把dev阶段的依赖比如pytest、black也写进去导致使用者装一个简单工具还要拉一堆工具链。测试和构建依赖应该放到独立的requirements-dev.txt里。python_requires3.7这个字段别小看。它会写进whl的元数据里Python版本不满足时pip会直接拒绝安装并提示用户升级或换版本。很多“我在A机器装得好好的换了机器装不上”的问题就是这个字段没写或者写错了。3.2 更现代的pyproject.toml写法如果你在2024年之后才开始写Python包我更推荐直接用pyproject.toml。这是在PEP 517/518之后定义的构建系统标准化格式好处是构建方案、项目元数据都集中在一个文件里不再依赖setup.py这种可执行脚本。对应的pyproject.toml示例[build-system] requires [setuptools61.0] build-backend setuptools.build_meta [project] name mytool version 1.0.0 description 用于清洗和分析日志的工具库 requires-python 3.7 license {text MIT} authors [ {name Your Name, email youexample.com} ] dependencies [ requests2.20, pandas1.0, ] [tool.setuptools.packages.find] include [mytool*]注意pyproject.toml里项目的元数据全部放在[project]表格下而dependencies就是install_requires的替代品写法是数组格式。build-backend指定用setuptools的构建后端。如果你用的是src布局[tool.setuptools.packages.find]要加一行where [src]。我的建议是新项目直接用pyproject.toml一条路走到底老项目保持setup.py别强行迁移因为迁移时需要重新梳理入口脚本、打包数据文件等细节容易踩坑。两种写法的打包命令完全一样下面的操作不区分配置格式。3.3 include_package_data和MANIFEST.in的作用很多第一次打包的人会忽略一个关键点非py文件不会自动进入whl。你的包如果依赖了配置文件、模板文件、图片资源比如mytool/config/default.yaml在setup.py里光写packagesfind_packages()是不行的还得加include_package_dataTrue并且通过MANIFEST.in把文件显式列出来include LICENSE include README.md recursive-include mytool/config *.yaml recursive-include mytool/templates *.html没有这一步别人装完你的包运行时会报FileNotFoundError而且很难排查因为你本地因为有源码目录所以一切正常但别人装的是wheel里面压根没有这几个文件。判断你的包有没有非py文件最简单的办法是等打包完成后用unzip -l xxx.whl看一眼文件列表这个我后面会演示。4. PyCharm里三种打包操作方式实测4.1 方式一Terminal里用setup.py bdist_wheel最经典PyCharm的Terminal面板本质上就是你操作系统里的命令行只是它已经帮你切到了当前项目目录。在这个终端里执行pip install wheel python setup.py bdist_wheel执行完项目根目录会多出build/、dist/和mytool.egg-info/三个东西。我们关心的dist/目录下会生成一个形如mytool-1.0.0-py3-none-any.whl的文件这就是打好的包。这个方式适合快速出包但它有一个明显的缺点它只调用build相关的命令跳过了一些规范的元数据校验和隔离构建逻辑也没有生成的源码包tar.gz。而且它要求你当前环境里setup.py可以直接执行如果用了pyproject.toml的现代后端老版本的setuptools可能会报兼容错误。4.2 方式二用python -m build标准化打包推荐这是我现在最常用的方式也是刚才在准备环境时安装build包的原因。在Terminal里执行python -m build --wheel如果还想同时生成源码包python -m build这个命令会自动创建一个隔离的构建环境在干净环境里安装好build后端要求的所有工具然后执行打包。好处很明显不会把你开发环境里乱七八糟的包影响混进构建过程也不会因为缺少某工具临时报错。跑完之后dist目录下不仅会有whl还会有mytool-1.0.0.tar.gz源码包。我建议把python -m build --wheel作为你的标准打包命令。它读的是pyproject.toml的[build-system]段也能兼容setup.py的老项目适用面最广步骤最少。4.3 方式三配置成PyCharm外部工具实现接近“一键打包”有些读者可能觉得每次都在Terminal里敲命令太原始希望在PyCharm里有个按钮点一下就打包。这里要澄清一个误区PyCharm本身并没有“打包whl”的菜单项它不是包管理器它只是个IDE。但我们可以通过External Tools功能把打包命令挂到右键菜单或者Tools菜单里。操作路径File - Settings - Tools - External Tools - 点加号填以下内容NameBuild WheelProgram项目虚拟环境里的python解释器路径。Windows通常是venv\Scripts\python.exemacOS和Linux是venv/bin/python。如果你不确定在Terminal里执行where python或which python就能看到。Arguments-m build --wheelWorking directory$ProjectFileDir$保存后点击Tools菜单你会看到多了一个“Build Wheel”选项点击就会在PyCharm内嵌的进度窗口里跑打包命令相当于一键打包。也可以右键项目根目录通过“External Tools”子菜单调用。如果你想像我一样更进一步可以把Program改成python.exe -m pip、Arguments改成install dist\mytool-1.0.0-py3-none-any.whl再配一个“Install Local Wheel”工具这样打包后顺手就能装到当前虚拟环境里测试。这一步能省不少来回切窗口的时间。4.4 三种方式的对比方式优点缺点适用场景setup.py bdist_wheel上手快兼容老项目不隔离构建环境依赖当前环境临时快速出包python -m build标准、隔离、稳定需要先安装build包日常推荐PyCharm外部工具可视化、接近一键配置路径要手工调一次经常打包、想省操作的人我个人建议是日常用方式二工作流成熟后再花五分钟配置一次方式三。5. 打包后whl的安装验证与分发5.1 先别急着发本地验证一遍打包成功不代表交付成功。我见过太多人把whl发给别人结果要么import不到要么版本不对要么少文件。永远在打包机本地做一次干净的验证。验证的第一步是看看whl里到底有什么。在Terminal里执行cd dist tar -tf mytool-1.0.0-py3-none-any.whl如果系统没有tar可以用Python标准库python -m zipfile -l mytool-1.0.0-py3-none-any.whl看到的结果应该是一个类似如下的列表mytool/__init__.py mytool/core.py mytool/utils.py mytool-1.0.0.dist-info/METADATA mytool-1.0.0.dist-info/RECORD mytool-1.0.0.dist-info/WHEEL我每次都会重点检查两点一是包目录是否真的存在二是非py文件有没有进去。这里暴露问题比等别人装完报错再排查要高效十倍。验证完文件列表创建出一个全新的虚拟环境做安装测试python -m venv test_venv source test_venv/bin/activate # Windows: test_venv\Scripts\activate pip install mytool-1.0.0-py3-none-any.whl python -c import mytool; print(mytool.__version__)这一步能在两分钟内发现依赖缺失、包导入失败、入口脚本报错等绝大多数问题。我强烈建议把这段验证步骤写成一个shell脚本或者Makefile target每次发版都跑一遍形成肌肉记忆。5.2 平台标签与兼容性为什么有的whl别人装不了whl文件名中间那几段不是随便起的它有固定的结构{dist}-{version}(-{build})?-{python}-{abi}-{platform}.whl。以mytool-1.0.0-py3-none-any.whl为例py3适用于Python 3所有小版本none不依赖特定ABIany跨平台任何操作系统都能装这三个字段是纯Python包的标志。如果你的包里带了C扩展、用了Cython或者绑定了一些编译好的二进制那么生成的whl文件名会变成mytool-1.0.0-cp39-cp39-win_amd64.whl这种形态。这里cp39指CPython 3.9解释器win_amd64指Windows 64位平台。也就是说这个包只能在Windows 64位、Python 3.9环境里安装换到Mac或者Python 3.10就用不了。这也是为什么pandas、numpy这类科学计算库在PyPI上会同时存在大量不同命名的whl文件——每个平台、每个Python版本都要专门编译一份。你如果用PyInstaller、PySide这类工具打包复杂的桌面项目底层的很多处理逻辑也和whl的这个ABI机制有关。所以如果你的代码是纯Python保持py3-none-any是最理想的状态千万不要用某个特定解释器去打包而破坏通用性。一旦你发现打包产物名字里出现了cp和平台标识就要复盘一下是不是哪里引入了编译步骤。5.3 分发从共享文件到公司内网源本地验证通过后分发就是最后一步了。最常见的方式是把whl文件放到共享网盘或者直接通过IM发给同事对方保存后用pip安装即可。这种方法在只有一两个人的小团队里效率极高但在几十人的团队里就会遇到版本管理混乱问题。稍微正式一点可以搭一个简单的本地PyPI镜像源比如用devpi或nexus。把whl通过twine upload传上去然后让同事在pip配置里指定pip install mytool --index-url http://your-nexus:8081/repository/pypi-internal/simple如果你要把包发布到公开PyPI那流程是先安装twinepip install twine python -m build twine upload dist/*twine会要求你输入PyPI账号的API token这里不展开细说。但对大多数个人工具和内部组件来说公开PyPI不是必须的你有更灵活的内部选项。6. 常见问题与排查技巧实录6.1 装完之后import不到先查包名和目录结构这个问题是我被问得最多的一种。打包成功、安装成功、但一import就报ModuleNotFoundError通常有三个原因第一find_packages()没找对包目录。如果你在项目里建了一个子目录放代码比如app/main/但没有给app下加__init__.pyfind_packages就只会找到app而不会找到app.main。解决方案是在每个子包目录下都放__init__.py或者在setup.py里用packages[app, app.main]显式声明。第二import的名字和包名不一致。namemytool只是pip安装时用的包名不代表import时的模块名。假设你的目录叫my_tool安装后就要import my_tool如果你写成import mytool怎么装都找不到。这个低级错误我犯过不止一次现在每次打包完我都会第一件事确认我到底该import多级路径里的哪一个名字。第三src布局漏了package_dir配置。如果你用了src目录但setup.py里没写package_dir{: src}setuptools会在项目根目录找包找到的是空集。这种whl也能生成但装完里面根本没有代码文件import必然失败。所以每次打完包看一眼whl的文件列表是最快的判断方式。6.2 Windows中文环境下的编码坑Windows中文字符集默认是GBK而whl构建工具链默认用UTF-8两者的碰撞会产生一个很典型的报错UnicodeDecodeError: utf-8 codec cant decode byte 0xb4 ...如果你的项目里有中文字符串资源而且项目目录路径或文件名里有中文打包时经常撞上这个错误。我在setup.py里读取README.md时遇到过在long_description字段上尤其常见。几个标准解法第一setup.py文件头部加# -*- coding: utf-8 -*-声明。第二读取文件时显式指定UTF-8编码不要用open(README.md).read()这种隐式编码方式。第三包名、项目目录、作者名等元数据尽量用纯英文ASCII字符避免中文导致的各种静默异常和平台兼容问题。代码内部的字符串用中文没问题但凡是涉及打包元数据和文件名的部分我建议全部英文。6.3 装完发现版本不对大概率是缓存和egg-info在作怪还有一种很容易被忽略的情况你改了代码打了新包同事pip install后发现代码还是旧的。排除掉同事没更新的可能后剩下的原因基本就是两个。第一打包时发现了旧的*.egg-info目录。这个目录里缓存了上一次打包时的元数据setuptools有时会读取它而不是重新扫描代码导致新版本号或新依赖没有生效。解法很简单每次正式打包前把build/、dist/和*.egg-info三个目录都删掉或者执行一个clean命令。我在项目里习惯配一个最简单的脚本rm -rf build dist mytool.egg-info .pytest_cache python -m build --wheel第二pip的本地缓存。当同一路径下存在相同版本号的whl时pip可能直接复用缓存里的旧文件。确认方法是执行安装时加--no-cache-dir强制绕过缓存或者干脆每次都升一个小版本号。这也印证了前面说的一次打包一个版本号别复用。6.4 其他几个高频坑速查现象原因解法提示invalid command bdist_wheel环境里没装wheelpip install wheel提示No module named setuptools虚拟环境没装或解释器异常pip install --upgrade setuptools wheel buildwhl文件几十MB甚至几百MB把.git、__pycache__、虚拟环境目录打进去了检查源目录不要在项目根目录下创建无关目录安装时提示不满足Requires-Pythonpython_requires写得太严格确认目标用户的Python版本放宽范围wheel解包后找不到数据文件没有配置MANIFEST.in或include_package_data补上配置并重新打包7. 我的一点工作流心得如果只看这篇文章的操作步骤你可能会觉得打包whl不过就是几条命令的事。但实际上真正值得养成的不是命令而是每次发版都按同一套流程走的习惯。我现在的工作流是这样的日常开发全在PyCharm里项目用pyproject.toml管理元数据开发过程不关心打包。到要发版的那天先在PyCharm的Terminal里跑一遍测试确认绿了然后执行清理并调用python -m build --wheel。接着我去dist目录看一眼whl文件列表再开一个干净的临时venv安装测试确认能import、能调用、性能正常最后才把whl发到内网源或者发给同事。这套流程的全部操作加起来不到五分钟但它帮我挡掉过无数次怎么你这里能跑我那里不行的尴尬。打包这件事本质上是把你本地开发环境和别人使用环境的差异提前暴露出来。你多花在这上面的每一分钟都是替将来排查问题省下的十倍时间。最后分享一个小技巧如果你经常需要在多个Python版本上测试自己的包是否兼容可以在本地装一个tox或nox用几条命令自动创建3.7、3.9、3.11等多个虚拟环境分别安装并跑测试。虽然这超出了打包本身的范畴但我实测下来它能把whl在这台机器上能用在那台机器上报错的概率再降一个数量级值得一试。