Python构建包打包.whl文件及使用.whl文件安装包指南

目录

• 一、准备一个最简单的包示例
• 1. 创建项目目录
• 二、编写包的源码
• 1. 创建src/mypackage目录
• 2. 创建__init__.py
• 3. 创建核心模块core.py
• 三、配置打包：pyproject.toml
• 四、可选：README.md和LICENSE
• 五、使用
• 六、构建.whl文件
• 1. 安装构建工具
• 2. 在项目根目录执行构建命令
• 七、使用.whl文件安装包
• 1. 在本机安装
• 2. 在另一台机器或离线环境安装
• 八、常见配置文件和写法汇总
• 1. 必需文件（最简）
• 2. 推荐增加的文件
• 3.pyproject.toml常见字段说明（Setuptools 方式）
• 九、补充：使用传统setup.py的方式（可选了解）
• 1. 创建setup.py
• 2. 构建 whl
• 十、完整示例小结
• 总结 

下面用一个完整、可运行的示例，从零开始演示：

• 如何自己构建一个 Python 包
• 如何打包成 .whl 文件
• 如何用 .whl 文件安装这个包

会覆盖到常用的配置文件、目录结构和具体命令。

假设我们要发布一个叫做 mypackage 的包，里面只有一个函数：add(a, b)，返回两个数的和。

在任意目录下创建项目根目录，例如：

mkdir mypackage-project
cd mypackage-project

项目最终结构大致如下（先给一个概览，后面逐个创建）：

mypackage-project/
├─ src/
│  └─ mypackage/
│     ├─ __init__.py
│     └─ core.py
├─ tests/
│  └─ test_core.py            # 可选
├─ pyproject.toml
├─ README.md
└─ LICENSE                    # 可选

说明：

• 使用 src/ 目录结构是目前官方推荐的做法，能避免一些导入问题。
• mypackage 是发布后用户 import 时用到的包名。

mkdir -p src/mypackage

__init__.py 表示这是一个包，并且可以在这里定义对外暴露的接口。

src/mypackage/__init__.py：

"""
mypackage
一个示例 Python 包，用于演示如何打包并生成 whl 文件。
"""
from .core import add
__all__ = ["add"]
__version__ = "0.1.0"

src/mypackage/core.py：

def add(a: float, b: float) -> float:
    """返回两个数字的和"""
    return a + b

从 Python 3.8+ 开始，推荐使用 PEP 517/518 的 pyproject.toml 来管理构建配置，这也是目前最主流、官方推荐的方式，比老的 setup.py 更简单清晰。

在项目根目录创建 pyproject.toml：

[build-system]
# 指定构建后端，常用的有 setuptools、hatchling、poetry 等
# 这里使用 setuptools 作为示例
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "mypackage"                # 包名（发布到 PyPI 时的名字）
version = "0.1.0"                 # 版本号
description = "A simple demo package for building wheel files."
readme = "README.md"              # 项目说明文件
requires-python = ">=3.8"
license = {text = "MIT"}          # 简单写法，也可以引用 LICENSE 文件

authors = [
  { name="Your Name", email="you@example.com" }
]

# 安装此包时所需的依赖
dependencies = [
  # "requests>=2.0.0",  # 示例：如果你的包依赖 requests
]

# 给工具和用户看的分类信息，可选
classifiers = [
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3 :: Only",
  "License :: OSI Approved :: MIT License",
  "Operating System :: OS Independent",
]

# 可选：项目主页、代码仓库等
[project.urls]
"Homepage" = "https://example.com/mypackage"
"Source" = "https://github.com/yourname/mypackage"

核心点：

• [build-system] 告诉 pip 等工具如何构建你的包。
• [project] 描述这个包的元数据（名字、版本号、依赖等）。

在项目根目录下创建一个简单的 README.md（安装后在 PyPI 上会展示）：

README.md：

# mypackage
一个示例 Python 包，用于演示如何从零构建并生成 `.whl` 文件。
## 安装
```bash
pip install mypackage

from mypackage import add

print(add(1, 2))  # 输出: 3

许可证 `LICENSE` 可以写常见的 MIT、Apache-2.0 等，这里略过内容。
---
## 五、可选：添加简单测试
虽然不是构建 whl 必需的，但建议有基本测试。
```bash
mkdir tests

tests/test_core.py：

from mypackage import add

def test_add():
    assert add(1, 2) == 3
    assert add(-1, 1) == 0

可以用 pytest 来跑测试：

pip install pytest
pytest

推荐使用 build（官方推荐构建前端）：

pip install build

确保当前路径是 mypackage-project 的根目录（和 pyproject.toml 同级）：

python -m build

执行成功后，你会看到类似输出，并在项目目录下生成两个目录：

dist/
    mypackage-0.1.0-py3-none-any.whl
    mypackage-0.1.0.tar.gz

其中：

• .whl 是你想要的 “轮子” 文件（wheel）
• .tar.gz 是源码包（source distribution）

如果只想生成 wheel，可以：

python -m build --wheel

假设当前仍在 mypackage-project 目录下：

pip install dist/mypackage-0.1.0-py3-none-any.whl

安装后可以在任意地方使用：

>>> from mypackage import add
>>> add(2, 5)
7

只需要把 dist/mypackage-0.1.0-py3-none-any.whl 拷贝到目标机器上，然后执行：

pip install mypackage-0.1.0-py3-none-any.whl

不需要源代码，也不需要联网（前提是你的包没有需要在线安装的新依赖，或者依赖也通过 whl 提前准备好）。

• pyproject.toml
• src/mypackage/__init__.py
• 你的实际代码文件（如 src/mypackage/core.py）

• README.md
• LICENSE
• tests/ 目录（配合 pytest）

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

[project]
name = "mypackage"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.8"
license = {text = "MIT"}

authors = [
  { name="Your Name", email="you@example.com" }
]

dependencies = [
  "requests>=2.0.0",
  "numpy>=1.24",
]

classifiers = [
  "Programming Language :: Python :: 3",
  "License :: OSI Approved :: MIT License",
]

[project.urls]
"Homepage" = "..."
"Source" = "..."
"Bug Tracker" = "..."

虽然现在更推荐 pyproject.toml，但很多老项目仍在用 setup.py。

如果你想了解一下传统方式，可以这样：

在项目根目录创建 setup.py：

from setuptools import setup, find_packages

setup(
    name="mypackage",
    version="0.1.0",
    description="A simple demo package for building wheel files.",
    author="Your Name",
    author_email="you@example.com",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    python_requires=">=3.8",
    install_requires=[
        # "requests>=2.0.0",
    ],
)

pip install wheel setuptools
python setup.py bdist_wheel

会在 dist/ 下生成 .whl 文件，同样可以用 pip install 安装。

注意：
新项目优先用 pyproject.toml，setup.py 更适合作为兼容旧项目的方式。

1. 创建目录结构：

mypackage-project/
├─ src/
│  └─ mypackage/
│     ├─ __init__.py
│     └─ core.py
├─ pyproject.toml
├─ README.md
└─ tests/...

2. pyproject.toml 用 setuptools 作为构建后端
3. 写好代码和 __init__.py
4. 安装构建工具：pip install build
5. 在项目根执行：python -m build --wheel
6. 在 dist/ 中得到 .whl 文件
7. 使用 pip install dist/xxx.whl 安装使用

到此这篇关于Python构建包打包.whl文件及使用.whl文件安装包的文章就介绍到这了,更多相关Python打包.whl文件及使用内容请搜索风君子博客以前的文章或继续浏览下面的相关文章希望大家以后多多支持风君子博客！

您可能感兴趣的文章:

• 手把手教你打包Python项目为whl文件
• Python将源码打包成.whl文件的完整指南