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

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

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

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

一、准备一个最简单的包示例

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

1. 创建项目目录

bash 复制代码

mkdir mypackage-project
cd mypackage-project

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

text 复制代码

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

说明：

使用 src/ 目录结构是目前官方推荐的做法，能避免一些导入问题。

mypackage 是发布后用户 import 时用到的包名。

二、编写包的源码

1. 创建 `src/mypackage` 目录

bash 复制代码

mkdir -p src/mypackage

2. 创建 `init.py`

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

src/mypackage/__init__.py：

python 复制代码

"""
mypackage

一个示例 Python 包，用于演示如何打包并生成 whl 文件。
"""

from .core import add

__all__ = ["add"]

__version__ = "0.1.0"

3. 创建核心模块 `core.py`

src/mypackage/core.py：

python 复制代码

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

三、配置打包：`pyproject.toml`

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

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

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` 和 `LICENSE`

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

README.md：

markdown 复制代码

# mypackage

一个示例 Python 包，用于演示如何从零构建并生成 `.whl` 文件。

## 安装

```bash
pip install mypackage

使用

python 复制代码

from mypackage import add

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

复制代码

许可证 `LICENSE` 可以写常见的 MIT、Apache-2.0 等，这里略过内容。

---

## 五、可选：添加简单测试

虽然不是构建 whl 必需的，但建议有基本测试。

```bash
mkdir tests

tests/test_core.py：

python 复制代码

from mypackage import add

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

可以用 pytest 来跑测试：

bash 复制代码

pip install pytest
pytest

六、构建 `.whl` 文件

1. 安装构建工具

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

bash 复制代码

pip install build

2. 在项目根目录执行构建命令

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

bash 复制代码

python -m build

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

text 复制代码

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

其中：

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

如果只想生成 wheel，可以：

bash 复制代码

python -m build --wheel

七、使用 `.whl` 文件安装包

1. 在本机安装

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

bash 复制代码

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

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

python 复制代码

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

2. 在另一台机器或离线环境安装

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

bash 复制代码

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

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

八、常见配置文件和写法汇总

1. 必需文件（最简）

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

2. 推荐增加的文件

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

3. `pyproject.toml` 常见字段说明（Setuptools 方式）

toml 复制代码

[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" = "..."

九、补充：使用传统 `setup.py` 的方式（可选了解）

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

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

1. 创建 `setup.py`

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

python 复制代码

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",
    ],
)

2. 构建 whl

bash 复制代码

pip install wheel setuptools
python setup.py bdist_wheel

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

注意：

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

十、完整示例小结

text 复制代码

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

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

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

十、完整示例小结

1. 创建 `src/mypackage` 目录

2. 创建 `init.py`

3. 创建核心模块 `core.py`

三、配置打包：`pyproject.toml`

四、可选：`README.md` 和 `LICENSE`

六、构建 `.whl` 文件

七、使用 `.whl` 文件安装包

3. `pyproject.toml` 常见字段说明（Setuptools 方式）

九、补充：使用传统 `setup.py` 的方式（可选了解）

1. 创建 `setup.py`