it编程 > 前端脚本 > Python

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

16人参与 • 2026-01-27 • Python

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

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

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

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

1. 创建项目目录

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

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 时用到的包名。

二、编写包的源码

1. 创建src/mypackage目录

mkdir -p src/mypackage

2. 创建__init__.py

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

src/mypackage/__init__.py：

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

3. 创建核心模块core.py

src/mypackage/core.py：

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

三、配置打包：pyproject.toml

从 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和license

在项目根目录下创建一个简单的 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

六、构建.whl文件

1. 安装构建工具

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

pip install build

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

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

python -m build

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

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

其中：

如果只想生成 wheel，可以：

python -m build --wheel

七、使用.whl文件安装包

1. 在本机安装

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

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

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

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

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

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

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

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

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

1. 必需文件（最简）

2. 推荐增加的文件

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

[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：

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

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

总结 

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

赞 (0)

您想发表意见！！点此发布评论

推荐阅读

Python中self用法示例详解

01-27

python中argparse模块用法详解(小白入门)

01-27

Python中内置函数super()用法示例详解

01-27

pandas读取数据集的实现示例

01-27

Python实现批量重命名照片并按拍摄日期归类

01-27
windows系统下Boost.Python的配置和使用方法(新手教学)

windows系统下Boost.Python的配置和使用方法(新手教学)

01-27

猜你喜欢

版权声明：本文内容由互联网用户贡献，该文观点仅代表作者本人。本站仅提供信息存储服务，不拥有所有权，不承担相关法律责任。 如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 2386932994@qq.com 举报，一经查实将立刻删除。

发表评论