Python项目打包并发布到PyPI的完整指南-Python教程-PHP中文网

Python项目打包并发布到PyPI的完整指南

DDD

发布： 2025-08-06 21:42:18

原创

1139人浏览过

Python项目打包并发布到PyPI的完整指南

本教程旨在为Python开发者提供将开源项目打包并发布到PyPI的详细步骤。内容涵盖项目结构调整、pyproject.toml文件的配置、使用build工具生成分发包，以及通过twine将包上传至PyPI。通过遵循本指南，您将能够使自己的Python项目通过pip命令轻松安装，极大提升项目的可访问性和影响力。

1. 理解Python包与PyPI

pypi（python package index）是python官方的第三方包仓库，类似于应用商店。开发者可以将自己编写的python库或应用程序打包并发布到pypi上，供全球用户通过pip install your-package-name命令进行安装和使用。将项目发布到pypi是提升其可发现性、可重用性和社区贡献度的关键一步。

2. 项目结构准备

在打包之前，建议对项目目录结构进行规范化调整。现代Python项目推荐使用src布局，即将所有可分发的源代码放在一个名为src的子目录中。这样可以清晰地分离源代码与项目根目录下的其他文件（如文档、测试、示例、配置文件等），避免在安装时误打包不必要的文件。

推荐的项目结构示例：

my_project/
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── module1.py
│       └── sub_package/
│           └── __init__.py
├── tests/
│   └── test_module1.py
├── docs/
│   └── index.rst
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore

登录后复制

其中，my_package是您实际希望发布到PyPI的Python包。

3. 配置项目元数据：pyproject.toml

pyproject.toml是PEP 517和PEP 621引入的现代Python项目配置标准，用于定义项目的元数据和构建系统信息。它取代了传统的setup.py和setup.cfg，提供了更简洁、统一的配置方式。

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

在项目根目录创建pyproject.toml文件，并添加以下基本配置：

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

[project]
name = "my-awesome-package" # 您的包在PyPI上的名称
version = "0.1.0"           # 包的版本号
description = "一个简洁的描述，说明您的包是做什么的"
readme = "README.md"        # 指向您的README文件
requires-python = ">=3.8"   # 支持的Python版本
license = { file = "LICENSE" } # 指向您的许可证文件
keywords = ["python", "library", "utility"] # 关键词，方便搜索
authors = [
    { name = "您的名字", email = "您的邮箱@example.com" }
]
classifiers = [ # 分类器，帮助用户发现您的包
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
    "Topic :: Software Development :: Libraries",
]
dependencies = [ # 您的包所依赖的其他PyPI包
    "requests>=2.28.1",
    "numpy",
]

[project.urls] # 项目相关的URL
Homepage = "https://github.com/your-username/my-awesome-package"
Repository = "https://github.com/your-username/my-awesome-package"
Issues = "https://github.com/your-username/my-awesome-package/issues"

登录后复制

关键字段说明：

[build-system]: 定义了构建工具和后端。这里使用setuptools作为构建后端。
[project]: 包含项目的核心元数据。
- name: 包的名称，用户将使用此名称通过pip安装。
- version: 包的版本号，遵循语义化版本（Semantic Versioning）规范。
- description: 简短的项目描述。
- readme: 指向项目的README文件，通常是Markdown格式。
- requires-python: 指定项目所需的Python版本范围。
- license: 指定项目的许可证信息。
- authors: 项目作者信息。
- classifiers: PyPI官方提供的一系列分类标签，有助于用户发现和理解您的包。
- dependencies: 项目运行时所需的外部依赖包列表。
[project.urls]: 提供项目的相关链接，如主页、代码仓库、问题跟踪等。

4. 构建分发包

配置好pyproject.toml后，您可以使用build工具来创建分发包。build工具会生成两种主要类型的分发文件：

.whl (Wheel): 预编译的二进制分发包，安装速度快。
.tar.gz (Source Distribution, sdist): 源代码分发包，包含所有源代码和元数据。

首先，确保您已安装build工具：

pip install build

登录后复制

然后在项目根目录（pyproject.toml所在的目录）执行构建命令：

python -m build

登录后复制

执行成功后，会在项目根目录下生成一个dist/目录，其中包含您的.whl和.tar.gz文件。例如：

PowerLib图书馆门户小程序

前后端完整代码包括本馆动态，新书来了，书籍榜单，服务指南，进馆预约，活动讲座预约等功能，采用腾讯提供的小程序云开发解决方案，无须服务器和域名预约管理：开始/截止时间/人数均可灵活设置，可以自定义客户预约填写的数据项预约凭证：支持线下到场后校验签到/核销/二维码自助签到等多种方式详尽的预约数据：支持预约名单数据导出Excel，打印

查看详情

dist/
├── my_awesome_package-0.1.0-py3-none-any.whl
└── my_awesome_package-0.1.0.tar.gz

登录后复制

5. 发布到PyPI

在将包发布到PyPI之前，建议先发布到TestPyPI进行测试。TestPyPI是一个用于测试的PyPI实例，可以帮助您验证发布流程而不会污染真实的PyPI。

步骤：

注册PyPI账户：
- 访问TestPyPI: https://www.php.cn/link/b62510e29bba2eb5af6ba88c3dce08e0
- 访问真实PyPI: https://www.php.cn/link/1f6325d1b1080e812e7b713ae61f4ebc
- 请分别注册账户，并牢记用户名和密码。
创建API Token (推荐)： 为了安全起见，推荐使用API Token而非用户名密码进行上传。登录您的PyPI或TestPyPI账户，在“Account settings”下找到“API tokens”部分，生成一个新的API Token，并妥善保存。
安装twine：twine是一个用于安全上传Python包到PyPI的工具。
```
pip install twine
```
登录后复制
上传到TestPyPI (测试)： 使用twine将dist/目录中的文件上传到TestPyPI：
```
twine upload --repository testpypi dist/*
```
登录后复制
twine会提示您输入TestPyPI的用户名（通常是__token__）和API Token。

上传成功后，您可以通过访问https://test.pypi.org/project/your-package-name/来查看您的包。您也可以尝试从TestPyPI安装您的包：
```
pip install --index-url https://test.pypi.org/simple/ --no-deps your-package-name
```
登录后复制
上传到真实PyPI (正式发布)： 当您在TestPyPI上验证无误后，即可将包上传到真实的PyPI：
```
twine upload dist/*
```
登录后复制
twine会提示您输入PyPI的用户名（通常是__token__）和API Token。

上传成功后，您的包将可在https://pypi.org/project/your-package-name/上找到，并且全球用户都可以通过pip install your-package-name进行安装。

6. 安装与验证

一旦您的包成功发布到PyPI，任何人都可以通过以下命令安装：

pip install my-awesome-package

登录后复制

安装后，您可以在Python环境中导入并使用您的包：

import my_awesome_package
# 调用您的包中的功能进行验证

登录后复制

7. 注意事项与最佳实践

版本管理： 每次发布新版本时，务必在pyproject.toml中更新version字段。建议遵循语义化版本（MAJOR.MINOR.PATCH）规范。
许可证： 确保您的项目包含一个许可证文件（如LICENSE），并在pyproject.toml中正确引用，以明确您的项目的使用条款。
README文件： 编写清晰、详细的README.md文件，包含项目介绍、安装指南、使用示例、API文档链接等，这将极大提升用户体验。
依赖管理： 仔细检查pyproject.toml中的dependencies列表，确保所有必要的运行时依赖都已列出。
持续集成/部署 (CI/CD)： 考虑使用GitHub Actions、GitLab CI/CD等工具自动化构建和发布流程，减少手动操作的错误，提高效率。
文档： 推荐使用Sphinx等工具生成专业的项目文档，并托管到Read the Docs等平台。

总结

将Python项目打包并发布到PyPI是开源贡献的重要一环，它使得您的代码能够被更广泛的社区发现、使用和贡献。通过遵循本教程中概述的步骤——规范项目结构、配置pyproject.toml、使用build工具构建分发包，以及通过twine上传到PyPI——您将能够成功地将自己的Python项目推向世界。持续维护和优化您的包，积极响应用户反馈，将有助于您的项目在Python生态系统中蓬勃发展。

以上就是Python项目打包并发布到PyPI的完整指南的详细内容，更多请关注php中文网其它相关文章！