Python篇---PyPI
把自己写的 Python 包发布到 PyPI(Python 官方包仓库)上,就能让全世界的人用 pip install 你的包名
直接安装了。这个过程并不复杂,就像 “给你的代码打个包,填个快递单,送到仓库” 一样。下面一步步讲清楚:
一、准备工作:安装必要工具
首先需要安装 3 个工具,它们是打包和上传的 “快递工具”:
pip install setuptools wheel twine
setuptools
:负责把你的代码打包成标准格式;wheel
:生成二进制安装包(安装更快);twine
:安全地上传包到 PyPI(比直接用setup.py
上传更安全)。
二、整理你的项目结构
发布前,你的项目需要有固定的 “文件夹结构”,就像快递需要标准包装一样。假设你的包叫 mypackage
,结构应该长这样:
mypackage_project/ # 项目根目录(名字随便起)
├── mypackage/ # 你的包文件夹(真正被安装的部分)
│ ├── __init__.py # 包的标识文件(必须有)
│ ├── module1.py # 你的功能模块1
│ └── module2.py # 你的功能模块2
├── README.md # 说明文档(告诉别人你的包怎么用)
├── LICENSE # 许可证(告诉别人可以怎么用你的代码)
└── setup.py # 打包配置文件(核心!填“快递单”的地方)
关键文件说明:
-
mypackage/
:里面是你的核心代码,必须包含__init__.py
(可以为空,也可以写包的版本等信息)。 -
README.md
:用 Markdown 写的说明文档,会显示在 PyPI 页面上。内容包括:包的功能、安装方法、使用例子等。 -
LICENSE
:许可证文件,规定别人如何使用你的代码。推荐用 MIT 许可证(简单宽松),直接复制 MIT 模板 改一下名字和年份就行。 -
setup.py
:最核心的配置文件,告诉 PyPI 你的包叫什么、版本多少、依赖什么等。
三、填写 “快递单”:配置 setup.py
setup.py
就像快递单,必须填对信息才能顺利发布。下面是一个模板,把括号里的内容换成你自己的:
from setuptools import setup, find_packagessetup(name="mypackage", # 包的名字(PyPI 上必须唯一,重名会传不上去)version="0.1.0", # 版本号(格式:主版本.次版本.修订号,比如 1.0.2)author="你的名字",author_email="你的邮箱",description="一句话描述你的包是干嘛的",long_description=open("README.md").read(), # 从 README 读取详细描述long_description_content_type="text/markdown", # 说明 README 是 Markdown 格式url="你的项目地址(比如 GitHub 链接)",packages=find_packages(), # 自动找到所有包(比如 mypackage)classifiers=[ # 分类标签(帮助别人在 PyPI 上搜到你的包)"Programming Language :: Python :: 3","License :: OSI Approved :: MIT License","Operating System :: OS Independent",],python_requires=">=3.6", # 支持的 Python 版本install_requires=[ # 你的包依赖的其他包(比如需要 requests 就写进去)# "requests >= 2.25.0",]
)
注意:
name
必须在 PyPI 上独一无二,先去 PyPI 官网 搜一下,避免重名。version
每次更新包时必须递增(比如从 0.1.0 到 0.1.1),否则传不上去。
四、打包你的代码
配置好后,在项目根目录(mypackage_project/
)下运行以下命令,生成可上传的包文件:
python setup.py sdist bdist_wheel
运行成功后,会多出两个文件夹:
dist/
:里面是打包好的文件,比如mypackage-0.1.0.tar.gz
(源代码包)和mypackage-0.1.0-py3-none-any.whl
(二进制包)。build/
和*.egg-info/
:临时文件,不用管。
五、注册 PyPI 账号
要上传包,需要先在 PyPI 有账号:
- 打开 PyPI 注册页面,填邮箱、用户名、密码注册。
- 注册后去邮箱验证账号(否则传不上包)。
六、上传包到 PyPI
用 twine
工具上传 dist/
里的文件,安全又稳定:
twine upload dist/*
运行后会提示输入你的 PyPI 用户名和密码:
- 用户名:注册时的用户名(不是邮箱);
- 密码:注册时的密码(输入时屏幕不显示,输完回车就行)。
更安全的方式:用 API 令牌(推荐)
为了避免每次输密码,也更安全,可以用 PyPI 的 API 令牌:
- 登录 PyPI 后,进入 Account Settings -> API tokens;
- 点 “Add API token”,名字随便起(比如
upload-token
),范围选 “Entire account”; - 生成后复制令牌(格式:
pypi-xxxxxxxxxxxxxxxxxxxxxx
); - 上传时用令牌当密码,用户名为
__token__
:twine upload dist/* --username __token__ --password 你的令牌
七、测试:安装自己的包
上传成功后,过几分钟(PyPI 可能缓存),就能用 pip
安装了:
pip install mypackage
安装后,在 Python 里试试导入:
import mypackage
print(mypackage.__version__) # 输出 0.1.0 说明成功
八、更新你的包(后续迭代)
如果你的代码有更新,需要重新发布新版本:
- 修改
setup.py
里的version
(比如从 0.1.0 改成 0.1.1); - 重新打包:
python setup.py sdist bdist_wheel
; - 重新上传:
twine upload dist/*
(会自动覆盖同版本号?不,必须用新的版本号!)。
常见问题
- “包名已存在”:PyPI 上的包名是唯一的,换个名字(比如在你的名字后加后缀,
mypackage-你的名字
)。 - 上传失败提示 “403”:可能是账号没验证,或者版本号重复,或者包名被占用。
- README 显示乱码:检查
setup.py
里的long_description_content_type
是否设为text/markdown
。 - 依赖安装问题:确保
install_requires
里的依赖包在 PyPI 上存在。
总结
发布包到 PyPI 就 3 步核心:
- 按标准结构整理代码,写好
setup.py
; - 用
setup.py
打包生成dist/
文件; - 用
twine
上传到 PyPI。
这样全世界的人就能通过 pip install
用你的代码了,是不是很有成就感?刚开始可以先在 测试 PyPI(专门用来测试的仓库)练手,熟悉后再发到正式的 PyPI 上~