如何发布一个自己的Python包到PyPI？-Python教程-PHP中文网

答案：发布Python包需准备pyproject.toml（定义元数据和依赖）、README.md（项目说明）、LICENSE（授权条款）、__init__.py（声明包）和.gitignore（忽略无关文件），并通过build构建分发文件、twine上传至PyPI或TestPyPI测试，确保包可安装、功能正常且元数据无误。

如何发布一个自己的python包到pypi？

发布一个自己的Python包到PyPI，核心流程可以概括为：准备好你的项目结构和元数据，使用构建工具生成分发文件，最后通过

twine

登录后复制

工具上传到PyPI（或TestPyPI进行测试）。这听起来似乎有点技术性，但只要跟着步骤来，其实没那么复杂，更多的是细致和耐心。

解决方案

说实话，第一次尝试发布Python包到PyPI，我脑子里也一堆问号，各种配置文件和命令，感觉像在走迷宫。但走过一遍，你会发现它其实有一套清晰的逻辑。关键在于，我们要把自己的代码和相关信息，按照PyPI能理解的方式“打包”好。

这个过程，我们通常会从项目的结构开始。一个典型的Python包项目，它应该有一个清晰的目录结构，比如：

your_package_name/
├── src/
│   └── your_package_name/
│       ├── __init__.py
│       └── your_module.py
├── tests/
│   └── test_your_module.py
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore

登录后复制

这里

src

登录后复制

目录的使用是个好习惯，它能确保你在本地开发和安装时，行为是一致的。

pyproject.toml

登录后复制

是现代Python项目配置的核心，它取代了部分

setup.py

登录后复制

和

setup.cfg

登录后复制

的功能，让事情变得更统一。

立即学习“Python免费学习笔记（深入）”；

接下来，就是配置

pyproject.toml

登录后复制

文件。这里面包含了你的包名、版本、作者、描述、依赖等等关键信息。它告诉PyPI，你的包是什么，需要什么，以及如何安装。配置好这个文件，基本上你的包的“身份证”就办好了。

然后，你需要安装一些工具来帮助你构建和上传。

build

登录后复制

工具用来生成你的分发文件（

sdist

登录后复制

和

wheel

登录后复制

），

twine

登录后复制

则负责安全地将这些文件上传到PyPI。所以，在你的虚拟环境里跑一下

pip install build twine

登录后复制

是必不可少的。

有了工具，就可以开始构建了。在项目根目录下运行

python -m build

登录后复制

，它会在你的项目里创建一个

dist/

登录后复制

目录，里面就是你的

.tar.gz

登录后复制

（源码分发，sdist）和

.whl

登录后复制

（二进制分发，wheel）文件。这些就是你要上传到PyPI的东西。

在真正上传到PyPI之前，强烈建议你先上传到TestPyPI。这就像是一个模拟的PyPI环境，你可以测试你的包是否能被正确安装、导入和使用，而不会污染真实的PyPI。命令大概是

twine upload --repository testpypi dist/*

登录后复制

。你需要在TestPyPI上注册一个账号并获取API token。

确认在TestPyPI上一切正常后，你就可以放心地上传到真正的PyPI了。命令是

twine upload dist/*

登录后复制

。同样，你需要在PyPI上注册账号并获取API token。上传成功后，恭喜你，你的Python包就正式上线了！

Python包发布的必备文件有哪些，以及它们的作用？

要发布一个Python包，我们手头得有几份关键的“档案”，它们各自扮演着不可或缺的角色，缺了哪个都可能让你的包发布不顺利，或者即便发布了，用户也用得一头雾水。

首先，也是最重要的，是

pyproject.toml

登录后复制

文件。这是现代Python项目配置的“指挥中心”。它定义了你的包的元数据，比如包的名称（

name

登录后复制

）、版本号（

version

登录后复制

）、简短描述（

description

登录后复制

）、许可证（

license

登录后复制

）、作者信息（

authors

登录后复制

）、项目主页（

urls.homepage

登录后复制

）以及最重要的依赖项（

dependencies

登录后复制

）。它还指定了构建系统，通常是

setuptools

登录后复制

或

flit

登录后复制

等，告诉Python如何构建你的包。没有它，或者配置错误，你的包就无法被正确识别和构建。

其次是

README.md

登录后复制

。这个文件是你的包的“脸面”和“说明书”。它通常用Markdown格式编写，详细介绍你的包是做什么的、如何安装、如何使用、有哪些功能、有什么示例代码，甚至可以包含贡献指南。当用户在PyPI上浏览你的包时，首先看到的就是这个README的内容。一个清晰、详细的README能极大地提升用户体验，并吸引更多人使用你的包。如果你的

pyproject.toml

登录后复制

里指定了

readme = "README.md"

登录后复制

，那么PyPI就会自动抓取这个文件的内容作为包的详细描述。

然后是

license

登录后复制

文件。这就像是你的包的“使用条款”。它明确了其他人可以如何使用、分发和修改你的代码。选择一个合适的开源许可证（如MIT, Apache 2.0, GPLv3等）非常重要，它不仅保护了你的权益，也为使用者提供了法律保障。没有许可证的包，在法律上是默认不允许他人使用的，这会大大限制你包的传播。

接着是你的包的核心代码文件。这通常位于一个与包名同名的目录中，比如

src/your_package_name/

登录后复制

。在这个目录里，__init__.py
登录后复制
文件是必须的，它告诉Python这个目录是一个Python包。即使是空文件，它的存在也至关重要。你的所有模块文件（如

your_module.py

登录后复制

）都会放在这个目录下。

自由画布

百度文库和百度网盘联合开发的AI创作工具类智能体

查看详情

最后，虽然不是发布必需，但强烈建议包含

.gitignore

登录后复制

文件。它告诉Git哪些文件或目录不应该被版本控制，比如编译生成的文件、虚拟环境、缓存文件等等。这能让你的代码仓库保持整洁，避免上传不必要的文件到PyPI。虽然它不直接参与PyPI的发布流程，但它是良好项目管理实践的一部分。

如何正确配置

pyproject.toml

登录后复制

文件来定义我的Python包？

pyproject.toml

登录后复制

文件的配置，坦白讲，初次接触可能会觉得有点头大，因为它涉及一些标准和规范。但一旦你理解了其核心结构，你会发现它比旧的

setup.py

登录后复制

更加清晰和声明式。

pyproject.toml

登录后复制

主要由几个部分组成，最核心的是

[project]

登录后复制

和

[build-system]

登录后复制

。

[build-system]

登录后复制

部分： 这是文件开头通常会有的部分，它定义了你的项目使用什么工具来构建。对于大多数使用

setuptools

登录后复制

的项目来说，配置会是这样：

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

登录后复制

```
requires
```
登录后复制
: 列出了构建你的包所需要的依赖。
```
setuptools
```
登录后复制
是Python项目构建的基石，
```
wheel
```
登录后复制
则用于生成
```
.whl
```
登录后复制
格式的二进制分发包。
```
build-backend
```
登录后复制
: 指定了哪个模块来执行实际的构建操作。
```
setuptools.build_meta
```
登录后复制
是
```
setuptools
```
登录后复制
的官方构建后端。

[project]

登录后复制

部分： 这是你包的所有元数据定义的地方。它告诉PyPI你的包叫什么、版本多少、有什么功能等等。

[project]
name = "your-package-name" # 包名，在PyPI上是唯一的
version = "0.1.0"          # 包的版本号，遵循语义化版本规范
description = "A short description of your awesome package." # 简短描述
readme = "README.md"       # 指定README文件，内容会显示在PyPI页面
requires-python = ">=3.8"  # 包运行所需的Python版本
license = { file = "LICENSE" } # 指定许可证文件
authors = [
    { name = "Your Name", email = "your.email@example.com" },
]
keywords = ["python", "utility", "example"] # 关键词，方便搜索
classifiers = [ # 分类器，帮助用户在PyPI上筛选和发现你的包
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
    "Development Status :: 3 - Alpha", # 开发状态，例如Alpha, Beta, Production/Stable
]
dependencies = [ # 运行时依赖，pip install your-package-name 时会安装这些
    "requests>=2.20.0",
    "beautifulsoup4",
]

[project.urls] # 项目相关的URL链接
homepage = "https://github.com/yourusername/your-package-name"
repository = "https://github.com/yourusername/your-package-name"
documentation = "https://your-package-name.readthedocs.io/"

登录后复制

name
登录后复制
: 这是你在PyPI上发布的包名，必须是唯一的。建议使用小写字母和连字符。
version
登录后复制
: 包的版本号，通常遵循语义化版本（Semantic Versioning），例如
```
1.0.0
```
登录后复制
、
```
0.5.1-beta
```
登录后复制
。每次发布新版本时，这个数字必须增加。
description
登录后复制
: 一个简洁的单行描述。
readme
登录后复制
: 指向你的
```
README.md
```
登录后复制
文件。PyPI会抓取其内容作为包的详细描述。
requires-python
登录后复制
: 指定你的包兼容的Python版本范围，比如
```
">=3.8"
```
登录后复制
。
license
登录后复制
: 可以直接指向
```
license
```
登录后复制
文件，或者使用
```
text
```
登录后复制
字段直接嵌入许可证文本。
authors
登录后复制
: 你的名字和邮箱。
keywords
登录后复制
: 一些描述你包的关键词，有助于用户搜索。
classifiers
登录后复制
: 这是非常重要的元数据，用于对你的包进行分类。它们是预定义的字符串，描述了你的包的Python版本兼容性、许可证、操作系统兼容性、开发状态等。你可以在PyPI官方文档找到完整的列表。
dependencies
登录后复制
: 你的包在运行时所依赖的其他Python包。
```
pip
```
登录后复制
会在安装你的包时自动安装这些依赖。

[project.scripts]

登录后复制

或
[project.entry-points."console_scripts"]
登录后复制
：如果你想让你的包安装后提供一个命令行工具，可以在这里配置：

[project.scripts]
your-command = "your_package_name.module:main_function" # 例如：your-command 会执行 your_package_name/module.py 里的 main_function

登录后复制

或者，更推荐使用

entry-points

登录后复制

的方式：

[project.entry-points."console_scripts"]
your-command = "your_package_name.module:main_function"

登录后复制

这会创建一个可执行的脚本，用户可以直接在命令行输入

your-command

登录后复制

来运行你的程序。

配置

pyproject.toml

登录后复制

时，务必仔细检查每一个字段，尤其是

name

登录后复制

、

version

登录后复制

、

requires-python

登录后复制

和

dependencies

登录后复制

，这些直接影响到你的包能否被正确构建和使用。

在将Python包发布到PyPI之前，有哪些关键的测试和验证步骤？

在满怀信心地将你的Python包推送到PyPI之前，进行一系列严谨的测试和验证是至关重要的。这就像产品发布前的质量检测，能帮你避免很多不必要的麻烦，比如用户安装失败、功能不正常或者依赖冲突。我个人经验告诉我，这些步骤绝不能省。

首先，也是最基础的，是本地安装测试。在你构建完分发文件（

dist/

登录后复制

目录下的

.whl

登录后复制

和

.tar.gz

登录后复制

）后，尝试在全新的虚拟环境中安装你的包。你可以先创建一个新的虚拟环境，激活它，然后运行：

pip install dist/your_package_name-0.1.0-py3-none-any.whl
# 或者通过源码安装
pip install dist/your_package_name-0.1.0.tar.gz

登录后复制

安装完成后，尝试导入你的包，并运行其中的一些核心功能，确保一切按预期工作。如果你的包提供了命令行工具，也要尝试运行它们。这个步骤能帮你发现诸如

setup.py

登录后复制

（如果还在用）或

pyproject.toml

登录后复制

配置错误、文件缺失、入口点不正确等问题。

其次，运行单元测试和集成测试。你的项目应该包含一套完整的测试用例（通常放在

tests/

登录后复制

目录下）。在发布前，务必确保所有测试都能通过。这能验证你的代码逻辑是否正确，功能是否稳定。你可以使用

pytest

登录后复制

或

unittest

登录后复制

等测试框架来执行这些测试。如果测试失败，那就说明你的代码可能存在问题，需要修复后再考虑发布。

# 假设你使用 pytest
pip install pytest
pytest tests/

登录后复制

再者，使用

twine check

登录后复制

验证分发文件。

twine

登录后复制

工具不仅用于上传，它还有一个非常实用的

check

登录后复制

命令，可以帮你检查

dist/

登录后复制

目录下的分发文件是否符合PyPI的要求，比如

README.md

登录后复制

的格式是否正确，元数据是否完整等。

twine check dist/*

登录后复制

这个命令会给你一些有用的警告或错误信息，比如Markdown渲染问题，或者一些潜在的兼容性问题。及时修正这些问题，能确保你的包在PyPI页面上展示良好，并且不会因为格式问题被拒绝。

最后，也是最关键的，是上传到TestPyPI进行预发布测试。TestPyPI是一个与真实PyPI镜像的测试环境，你可以将你的包上传到这里，模拟真实的发布过程，而不会影响到PyPI上的正式包。

twine upload --repository testpypi dist/*

登录后复制

你需要先在TestPyPI上注册一个账号，并生成一个API token。上传成功后，你可以像在PyPI上一样，通过

pip install --index-url https://test.pypi.org/simple/ --no-deps your-package-name

登录后复制

来安装你的包，并在一个全新的环境中进行彻底的测试。检查你的包在TestPyPI上的页面是否显示正确，描述是否完整，依赖是否列出等。如果在TestPyPI上发现问题，你可以随意删除包并重新上传，直到满意为止。这个步骤能帮你捕捉到许多只有在真实发布环境下才能发现的问题，是发布前不可或缺的一环。

以上就是如何发布一个自己的Python包到PyPI？的详细内容，更多请关注php中文网其它相关文章！

大家都在看：

动态安装和使用 PyPi 包：在 PyInstaller 打包的软件中实现如何发布一个自己的Python包到PyPI？解决PyPI上传失败：理解reStructuredText描述渲染错误解决Twine上传PyPI时RST描述渲染失败问题解决Twine上传PyPI时reStructuredText描述渲染失败的问题

如何发布一个自己的Python包到PyPI？

解决方案

Python包发布的必备文件有哪些，以及它们的作用？

如何正确配置pyproject.toml登录后复制文件来定义我的Python包？

在将Python包发布到PyPI之前，有哪些关键的测试和验证步骤？

大家都在看：

如何正确配置
pyproject.toml
登录后复制
文件来定义我的Python包？