PyPI 发包全流程（手把手）

你有没有这种感觉：写了个好用的轮子，身边同事都在问“能不能 pip install”，结果你只能甩给他们一个GitHub链接。

其实把自己的代码发布到PyPI不难，10分钟就能搞定。但网上教程要么太老（setup.py 写法早就废弃了），要么漏掉关键步骤，发上去装不上，一堆人骂你。

今天手把手带你走一遍，保你能发、能装、能更新。

准备：目录结构长这样

先规划好项目结构，别乱七八糟往上怼。

my_package/
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── core.py
├── tests/
├── README.md
├── pyproject.toml
├── LICENSE
└── .gitignore

关键点说清楚：

• src布局（src/my_package）已经是2024年的标准写法了，比直接 my_package/ 在根目录要好很多
• __init__.py 必须有，不然Python不认这是个包
• pyproject.toml 是现在的核心配置文件，setup.py 那种老写法不推荐了

第一步：写 pyproject.toml

这个文件告诉pip怎么安装你的包，最重要。

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-package-nickname"
version = "0.1.0"
description = "一句话描述这包干啥的"
readme = "README.md"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "you@example.com"}
]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]
requires-python = ">=3.8"

[project.urls]
Homepage = "https://github.com/yourname/my-package"

坑在哪：

name 必须唯一，你随便写个 “utils” 肯定被人抢注了。建议加个前缀，比如 “wuxc-utils”，我之前随手写了个名字，上传的时候直接报错“名字已被占用”，只能改。

requires-python 别写太低，如果你用了 match-case 语法，那至少 >=3.10。

第二步：写 init.py

别小看这个文件，很多人发完包 pip install 成功，但 import 报错。

"""my_package: 一个简短描述"""

__version__ = "0.1.0"

from .coreimportMyClass

建议至少导出 __version__，这样用户装完可以 print(xxx.__version__) 验证安装成功。

第三步：写 README.md

这个会显示在你的PyPI项目页面上，别整太敷衍。

至少包含：

• 安装命令 pip install my-package
• 5行代码示例
• 几句话说明适用场景

markdown格式要正常，PyPI会自动渲染。

第四步：注册PyPI账号

这一步很多人漏掉，结果发包的时候才发现自己没账号。

去这两个网站注册：

• PyPI 测试站（先在这练手）：https://test.pypi.org/account/register/
• PyPI 正式站：https://pypi.org/account/register/

注意：现在PyPI强制开启两步验证（2FA），你得装个身份验证器App（Google Authenticator或者腾讯身份宝都行），别嫌麻烦，安全。

注册完先试试能不能登录，验证码能不能收上来。

第五步：生成token

登录PyPI后，点右上角 “Account Settings” → “API tokens” → “Add API token”。

Scope 选 “Entire account”（或者只选你的项目名字），然后复制token。

token长这样：pypi-xxxxxxxxxxxxx

关键：不要关掉这个页面，token只会显示一次。复制完立刻存到安全的地方（密码管理器、腾讯文档加密文档都行）。

第六步：配置 pip 凭证

在你的电脑上配置一下，告诉pip遇到这个token就用它。

在用户目录创建 ~/.pypirc 文件（Windows上是 C:\Users\你的用户名\）：

[pypi]
username = __token__
password = pypi-xxxxxxxxxxxxx（你的token）

Windows创建带点的文件有点烦，可以在PowerShell里用：

notepad$env:USERPROFILE\.pypirc

第七步：打包上传

先确保安装了打包工具：

pip install build twine

然后在你的项目根目录执行：

# 先到上级目录（假设你的项目在 my_package/）
cd my_package
python -m build

如果一切正常，会在 dist/ 目录下生成两个文件：

• my_package-0.1.0.tar.gz（源码包）
• my_package-0.1.0-py3-none-any.whl（wheel包）

然后上传：

# 先上传到测试站，验证一下
python -m twine upload --repository testpypi dist/*

测试站地址：https://test.pypi.org

在测试站验证能安装：

pip install --index-url https://test.pypi.org/simple/ my-package-nickname

如果测试没问题，再上传正式站：

python -m twine upload dist/*

第八步：验证安装

上传完成后，等个1-2分钟（PyPI同步需要时间），执行：

pip install my-package-nickname

然后验证：

importmy_package
print(my_package.__version__)

能打印出版本号，就算成功了。

更新版本

下次你想发布新版本，记得改 pyproject.toml 里的 version，然后：

# 重新打包
python -m build

# 上传
python -m twine upload dist/*

不需要改包名，pip会自动识别新版本。

你可能遇到的坑

1. twine upload 报错 “Invalid credentials”

检查 .pypirc 文件格式，username 必须是 __token__（带两个下划线），password 是 token 本身，不是你的登录密码。

2. 安装时报 “package metadata missing”

你的 pyproject.toml 里的 [project] 部分写错了，检查 name、version、description 这些必填字段。

3. import 找不到模块

检查你的目录结构，确保是 src/my_package/ 这种布局，而不是直接 my_package/ 在根目录。pip install 后会解压到 site-packages，如果目录不对，Python 找不到。

4. PyPI名字冲突

发包之前先去 https://pypi.org/search/?q=你的名字 搜一下，看看有没有人用过这个名字。有的话就换个前缀。

发个包拢共就这几步：

1. 规划目录结构（推荐src布局）
2. 写 pyproject.toml（现代写法）
3. 注册 PyPI 账号 + 开启2FA
4. 生成 API token
5. 配置 pip 凭证
6. 打包 + 先传测试站
7. 测试安装 + 没问题再传正式站

全程不用30分钟，但你从此就能理直气壮说“pip install xxx”了。

你发过PyPI包吗？遇到什么坑了？评论区聊聊。

没发过的朋友，现在就可以动手试了。有问题直接问，我来解答。

“无他，惟手熟尔”！有需要的用起来！