当前位置：首页 > 文章列表 > 文章 > python教程 > Python项目打包发布教程

Python项目打包发布教程

2025-08-11 13:00:35 0浏览收藏

“纵有疾风来，人生不言弃”，这句话送给正在学习文章的朋友们，也希望在阅读本文《Python项目打包发布PyPI教程》后，能够真的帮助到大家。我也会在后续的文章中，陆续更新文章相关的技术文章，有好的建议欢迎大家在评论留言，非常感谢！

从现有Python项目创建并发布PyPI包教程

本教程详细指导如何将现有Python项目打包并发布到PyPI。内容涵盖项目目录结构调整、使用pyproject.toml配置包元数据与构建系统、生成分发包，以及最终通过twine工具上传至PyPI的完整流程。旨在帮助开发者高效地将Python应用或库分享给社区，实现便捷的pip install安装。

PyPI（Python Package Index）是Python社区的官方第三方软件包仓库，通过将您的项目发布到PyPI，其他用户便能使用pip install your-package-name命令轻松安装和使用您的代码。本教程将引导您完成从项目准备到最终发布的每一个关键步骤。

1. 项目结构准备与规范

为了确保您的Python项目能够正确地被打包，建议遵循标准的项目结构。最推荐的做法是将所有可安装的源代码放置在一个专用的源目录（通常命名为src）中。

建议的项目结构示例：

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

关键点：

src/ 目录： 包含您实际希望作为PyPI包发布的Python源代码。这样做的好处是，可以清晰地区分源代码与项目中的其他文件（如测试文件、文档、构建脚本等），避免不必要的非源代码文件被打包进去。
your_package_name/： 这是您的Python包的顶级模块名，通常与您的项目名称保持一致或相似。其中必须包含一个__init__.py文件，即使是空的，它也能将该目录标记为一个Python包。
排除非必需文件： 像测试文件（tests/）、开发脚本、大型数据集等不应包含在最终的PyPI分发包中。pyproject.toml的配置和src目录的使用有助于自然地排除这些文件。

2. 配置 pyproject.toml 文件

pyproject.toml是现代Python打包的标准配置文件，它取代了传统的setup.py和setup.cfg，用于定义项目的元数据、构建系统以及依赖关系。

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

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

[project]
name = "your-package-name" # 您的包在PyPI上的名称
version = "0.1.0" # 包的版本号，遵循语义化版本（Semantic Versioning）
authors = [
  { name="Your Name", email="your.email@example.com" },
]
description = "A short description of your project." # 简短描述
readme = "README.md" # 指向您的README文件
requires-python = ">=3.8" # 兼容的Python版本
keywords = ["ai", "assistant", "debug"] # 关键词，有助于搜索
classifiers = [ # 分类器，描述您的项目
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
    "Development Status :: 3 - Alpha", # 开发状态
    "Intended Audience :: Developers",
]
dependencies = [ # 运行时依赖，pip会自动安装
    "requests>=2.25.1",
    "numpy",
    # 其他依赖...
]

[project.urls]
Homepage = "https://github.com/your-username/your-project-name" # 项目主页
"Bug Tracker" = "https://github.com/your-username/your-project-name/issues" # Bug追踪

[project.optional-dependencies] # 可选依赖，例如开发或测试依赖
dev = ["pytest", "twine", "build"]

[tool.setuptools.packages.find]
where = ["src"] # 告诉setuptools在src目录下查找包

pyproject.toml关键字段说明：

[build-system]： 定义了构建包所需的工具和后端。setuptools和wheel是常用的构建工具。
[project]： 包含包的所有元数据。
- name：您的包在PyPI上的唯一名称。
- version：包的版本号，每次发布新版本时都需要更新。
- authors：作者信息。
- description：包的简短描述。
- readme：指向您的README.md文件，PyPI会显示其内容。
- requires-python：指定包兼容的Python版本范围。
- keywords：有助于用户搜索您的包。
- classifiers：标准化的字符串，描述您的项目，例如许可证、操作系统、Python版本等。可以在PyPI官方文档中找到完整的分类器列表。
- dependencies：列出您的项目运行所需的第三方库及其版本要求。
[project.urls]： 提供项目相关的链接，如主页、bug追踪等。
[project.optional-dependencies]： 定义可选的依赖项，例如仅在开发或测试阶段需要的库。
[tool.setuptools.packages.find]： 如果您使用了src目录结构，此配置告诉setuptools在src目录中查找包。

3. 构建分发包

在配置好pyproject.toml之后，您可以使用build模块来生成分发包。

首先，确保您安装了build模块：

pip install build

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

python -m build

执行此命令后，会在项目根目录下生成一个名为dist/的目录。该目录中会包含两个文件：

.whl文件（Wheel）：这是一个预编译的二进制分发包，可以直接安装，通常是首选的安装方式。
.tar.gz文件（Source Distribution, sdist）：这是一个源代码分发包，包含您的项目源代码和其他元数据，可以在目标机器上进行编译和安装。

4. 上传到PyPI

在上传之前，您需要一个PyPI账户。如果还没有，请前往 PyPI官网注册。为了安全起见，建议使用API Token进行认证，而不是直接使用用户名和密码。

创建API Token： 登录PyPI账户后，导航到 "Account settings" -> "API tokens"，创建一个新的API Token，并务必保存好，因为它只会显示一次。
安装twine： twine是一个用于安全上传Python包到PyPI的工具。
```
pip install twine
```
上传包： 在项目根目录，使用twine上传dist/目录中的所有文件：
```
twine upload dist/*
```
twine会提示您输入PyPI用户名和密码。对于API Token，用户名输入__token__，密码则输入您之前保存的API Token（通常以pypi-开头）。
如果您想先测试上传过程而不发布到正式的PyPI，可以使用TestPyPI：
```
twine upload --repository testpypi dist/*
```
TestPyPI的注册和API Token创建过程与正式PyPI类似，但它们是独立的。

成功上传后，您的包就可以通过pip install your-package-name命令进行安装了。

注意事项

版本管理： 每次发布新版本时，务必更新pyproject.toml中的version字段。遵循语义化版本（Semantic Versioning）规则（MAJOR.MINOR.PATCH），例如1.0.0、1.0.1、1.1.0等。
许可证（License）： 在您的项目中包含一个许可证文件（如LICENSE），并在pyproject.toml中通过classifiers指定，这对于开源项目至关重要。
README.md： 提供清晰、详细的README.md文件，包含项目简介、安装指南、使用示例、贡献方式等，这会极大地提升您项目的可发现性和可用性。
依赖项： 确保pyproject.toml中的dependencies列表准确无误，只包含运行时必需的依赖，并指定合适的版本范围。
测试： 在发布之前，务必对您的包进行充分的测试，确保其功能完善且稳定。
虚拟环境： 在开发和打包过程中，始终使用虚拟环境，以避免包依赖冲突。

总结

将Python项目打包并发布到PyPI是一个相对直接的过程，但需要注意一些细节。通过遵循本教程中概述的步骤——规范项目结构、精确配置pyproject.toml、使用build工具构建分发包，以及利用twine安全上传——您将能够成功地将您的Python项目发布到PyPI，使其可供全球Python社区轻松安装和使用。这不仅是分享您的工作成果的有效方式，也是对开源社区的重要贡献。

理论要掌握，实操不能落！以上关于《Python项目打包发布教程》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！