如何发布一个 Python 包到 PyPI

已于 2025年11月10日 14:52 修改访问次数：0

非常好的问题 👍——你想要的是如何发布一个 Python 包到 PyPI（也就是别人可以通过 pip install your-package-name 来安装）。

下面我给你完整讲一遍现代的 Python 包发布流程（2025年通用方式），包含工具选择、目录结构、打包、上传和匹配安装。

🧭 一、整体流程概览

发布一个 Python 包的完整流程如下：

写代码
   ↓
创建项目结构 (包含 pyproject.toml)
   ↓
构建分发包 (build)
   ↓
上传到 PyPI (twine)
   ↓
用户通过 pip install your-package-name 安装

🧩 二、标准项目结构（现代推荐）

以包名 mypackage 为例：

mypackage/
│
├── pyproject.toml          ← 必须，有关构建信息（取代 setup.py）
├── README.md               ← 项目说明
├── LICENSE
├── src/                    ← 推荐使用 src 布局
│   └── mypackage/
│       ├── __init__.py
│       └── core.py
└── tests/
    └── test_core.py

📌 `pyproject.toml` 示例

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "mypackage"
version = "0.1.0"
description = "A simple example package"
readme = "README.md"
requires-python = ">=3.8"
license = {text = "MIT"}
authors = [
  { name="Your Name", email="you@example.com" }
]
dependencies = [
  "requests",
]

[project.urls]
Homepage = "https://github.com/yourname/mypackage"

👉 现在官方推荐使用 pyproject.toml（setup.py 可选）。

⚙️ 三、构建分发文件

安装构建工具：

pip install build

构建：

python -m build

执行后会生成：

dist/
├── mypackage-0.1.0.tar.gz      ← 源代码包
└── mypackage-0.1.0-py3-none-any.whl  ← Wheel 包（推荐）

🚀 四、上传到 PyPI

安装上传工具：

pip install twine

✅ 上传到正式 PyPI：

twine upload dist/*

系统会提示输入用户名和密码（PyPI账户）。

✅ 或上传到测试 PyPI（推荐先试）

twine upload --repository testpypi dist/*

然后安装测试版：

pip install -i https://test.pypi.org/simple/ mypackage

🧠 五、用户如何“匹配安装”

上传后，别人就可以直接：

pip install mypackage

如果你指定了 Python 版本和依赖，pip 会自动匹配：

版本号匹配（如 mypackage>=0.1.0,<1.0.0）
Python 版本匹配（如 >=3.8）
平台匹配（Wheel 的 py3-none-any.whl 表示通用包）

🧱 六、版本与依赖管理

📦 版本规则（遵循 PEP 440）

类型	示例	含义
开发版	0.1.0.dev1	开发中版本
预发布	0.1.0a1 / 0.1.0b1 / 0.1.0rc1	alpha / beta / rc
正式版	0.1.0	稳定发布
后缀	0.1.0.post1	发布后修订

🧩 七、常见问题

问题	原因	解决方案
❌ `invalid command 'bdist_wheel'`	没装 `wheel`	`pip install wheel`
❌ 上传失败（权限）	PyPI 账号或 token 错误	检查 `~/.pypirc`
❌ “Name already taken”	包名被占用	换名字（PyPI 唯一）
⚠️ `README` 编码错误	Markdown 解析错误	用 UTF-8 编码保存

🧰 八、可选优化

✅ 用 setuptools-scm 自动生成版本号
✅ 用 hatch, flit, poetry 等现代工具简化构建
✅ 用 GitHub Actions 自动打包上传（CI/CD）

🔐 九、配置 PyPI 登录（可选）

在 ~/.pypirc 中配置：

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-AgENdGV...

[testpypi]
username = __token__
password = pypi-AgENdGV...

✅ 十、总结一览

步骤	命令
安装工具	`pip install build twine`
构建包	`python -m build`
测试上传	`twine upload --repository testpypi dist/*`
安装测试包	`pip install -i https://test.pypi.org/simple/ mypackage`
正式上传	`twine upload dist/*`
安装使用	`pip install mypackage`

如果你告诉我你的包现在是：

用 setup.py 还是 pyproject.toml；
想上传到正式 PyPI 还是测试 PyPI；

我可以帮你写出最简可运行模板，直接可用来发布。

要不要我帮你写一个模板项目（比如 myutils）？

文章标签：