Python構(gòu)建包打包.whl文件及使用.whl文件安裝包指南
下面用一個完整、可運(yùn)行的示例，從零開始演示：
- 如何自己構(gòu)建一個 Python 包
- 如何打包成
.whl文件 - 如何用
.whl文件安裝這個包
會覆蓋到常用的配置文件、目錄結(jié)構(gòu)和具體命令。
一、準(zhǔn)備一個最簡單的包示例
假設(shè)我們要發(fā)布一個叫做 mypackage 的包，里面只有一個函數(shù)：add(a, b)，返回兩個數(shù)的和。
1. 創(chuàng)建項(xiàng)目目錄
在任意目錄下創(chuàng)建項(xiàng)目根目錄，例如：
mkdir mypackage-project cd mypackage-project
項(xiàng)目最終結(jié)構(gòu)大致如下（先給一個概覽，后面逐個創(chuàng)建）：
mypackage-project/ ├─ src/ │ └─ mypackage/ │ ├─ __init__.py │ └─ core.py ├─ tests/ │ └─ test_core.py # 可選 ├─ pyproject.toml ├─ README.md └─ LICENSE # 可選
說明：
- 使用
src/目錄結(jié)構(gòu)是目前官方推薦的做法，能避免一些導(dǎo)入問題。mypackage是發(fā)布后用戶import時用到的包名。
二、編寫包的源碼
1. 創(chuàng)建src/mypackage目錄
mkdir -p src/mypackage
2. 創(chuàng)建__init__.py
__init__.py 表示這是一個包，并且可以在這里定義對外暴露的接口。
src/mypackage/__init__.py：
""" mypackage 一個示例 Python 包，用于演示如何打包并生成 whl 文件。 """ from .core import add __all__ = ["add"] __version__ = "0.1.0"
3. 創(chuàng)建核心模塊core.py
src/mypackage/core.py：
def add(a: float, b: float) -> float:
"""返回兩個數(shù)字的和"""
return a + b
三、配置打包：pyproject.toml
從 Python 3.8+ 開始，推薦使用 PEP 517/518 的 pyproject.toml 來管理構(gòu)建配置，這也是目前最主流、官方推薦的方式，比老的 setup.py 更簡單清晰。
在項(xiàng)目根目錄創(chuàng)建 pyproject.toml：
[build-system]
# 指定構(gòu)建后端，常用的有 setuptools、hatchling、poetry 等
# 這里使用 setuptools 作為示例
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "mypackage" # 包名（發(fā)布到 PyPI 時的名字）
version = "0.1.0" # 版本號
description = "A simple demo package for building wheel files."
readme = "README.md" # 項(xiàng)目說明文件
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",
]
# 可選：項(xiàng)目主頁、代碼倉庫等
[project.urls]
"Homepage" = "https://example.com/mypackage"
"Source" = "https://github.com/yourname/mypackage"
核心點(diǎn)：
[build-system]告訴pip等工具如何構(gòu)建你的包。[project]描述這個包的元數(shù)據(jù)（名字、版本號、依賴等）。
四、可選：README.md和LICENSE
在項(xiàng)目根目錄下創(chuàng)建一個簡單的 README.md（安裝后在 PyPI 上會展示）：
README.md：
# mypackage 一個示例 Python 包，用于演示如何從零構(gòu)建并生成 `.whl` 文件。 ## 安裝 ```bash pip install mypackage
五、使用
from mypackage import add print(add(1, 2)) # 輸出: 3
許可證 `LICENSE` 可以寫常見的 MIT、Apache-2.0 等，這里略過內(nèi)容。 --- ## 五、可選：添加簡單測試 雖然不是構(gòu)建 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
六、構(gòu)建.whl文件
1. 安裝構(gòu)建工具
推薦使用 build（官方推薦構(gòu)建前端）：
pip install build
2. 在項(xiàng)目根目錄執(zhí)行構(gòu)建命令
確保當(dāng)前路徑是 mypackage-project 的根目錄（和 pyproject.toml 同級）：
python -m build
執(zhí)行成功后，你會看到類似輸出，并在項(xiàng)目目錄下生成兩個目錄：
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
七、使用.whl文件安裝包
1. 在本機(jī)安裝
假設(shè)當(dāng)前仍在 mypackage-project 目錄下：
pip install dist/mypackage-0.1.0-py3-none-any.whl
安裝后可以在任意地方使用：
>>> from mypackage import add >>> add(2, 5) 7
2. 在另一臺機(jī)器或離線環(huán)境安裝
只需要把 dist/mypackage-0.1.0-py3-none-any.whl 拷貝到目標(biāo)機(jī)器上，然后執(zhí)行：
pip install mypackage-0.1.0-py3-none-any.whl
不需要源代碼，也不需要聯(lián)網(wǎng)（前提是你的包沒有需要在線安裝的新依賴，或者依賴也通過 whl 提前準(zhǔn)備好）。
八、常見配置文件和寫法匯總
1. 必需文件（最簡）
pyproject.tomlsrc/mypackage/__init__.py- 你的實(shí)際代碼文件（如
src/mypackage/core.py）
2. 推薦增加的文件
README.mdLICENSEtests/目錄（配合 pytest）
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" = "..."
九、補(bǔ)充：使用傳統(tǒng)setup.py的方式（可選了解）
雖然現(xiàn)在更推薦 pyproject.toml，但很多老項(xiàng)目仍在用 setup.py。
如果你想了解一下傳統(tǒng)方式，可以這樣：
1. 創(chuàng)建setup.py
在項(xiàng)目根目錄創(chuàng)建 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. 構(gòu)建 whl
pip install wheel setuptools python setup.py bdist_wheel
會在 dist/ 下生成 .whl 文件，同樣可以用 pip install 安裝。
注意：
新項(xiàng)目優(yōu)先用pyproject.toml，setup.py更適合作為兼容舊項(xiàng)目的方式。
十、完整示例小結(jié)
- 創(chuàng)建目錄結(jié)構(gòu)：
mypackage-project/ ├─ src/ │ └─ mypackage/ │ ├─ __init__.py │ └─ core.py ├─ pyproject.toml ├─ README.md └─ tests/...
pyproject.toml用 setuptools 作為構(gòu)建后端- 寫好代碼和
__init__.py - 安裝構(gòu)建工具：
pip install build - 在項(xiàng)目根執(zhí)行：
python -m build --wheel - 在
dist/中得到.whl文件 - 使用
pip install dist/xxx.whl安裝使用
總結(jié)
到此這篇關(guān)于Python構(gòu)建包打包.whl文件及使用.whl文件安裝包的文章就介紹到這了,更多相關(guān)Python打包.whl文件及使用內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
Python輪播圖與導(dǎo)航欄功能的實(shí)現(xiàn)流程全講解
這篇文章主要介紹了Python項(xiàng)目輪播圖功能實(shí)現(xiàn)和導(dǎo)航欄的實(shí)現(xiàn)，文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值，需要的朋友們下面隨著小編來一起學(xué)習(xí)吧2022-09-09
Python異常對象Exception基礎(chǔ)類異常捕捉
這篇文章主要為大家介紹了Python異常對象異常捕捉及Exception基礎(chǔ)類，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進(jìn)步，早日升職加薪2022-06-06
2020版Python學(xué)習(xí)路線圖(附學(xué)習(xí)資料)
這篇文章主要介紹了Python學(xué)習(xí)路線圖(2020最新版)，小編覺得挺不錯的，現(xiàn)在分享給大家，也給大家做個參考。一起跟隨小編過來看看吧2020-09-09
python實(shí)現(xiàn)從ftp服務(wù)器下載文件
這篇文章主要為大家詳細(xì)介紹了python實(shí)現(xiàn)從ftp服務(wù)器下載文件，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價值，感興趣的小伙伴們可以參考一下2020-03-03
如何在Conda環(huán)境中降級Python版本詳細(xì)指南
在Conda環(huán)境中查看Python版本是一個常見需求,特別是當(dāng)您管理多個環(huán)境時,這篇文章主要介紹了如何在Conda環(huán)境中降級Python版本的相關(guān)資料,文中通過代碼介紹的非常詳細(xì),需要的朋友可以參考下2025-11-11
解決AttributeError:'NoneTypeobject'?has?no?attrib
這篇文章主要介紹了解決AttributeError:?‘NoneType‘?object?has?no?attribute?‘Window‘的問題(親測有效),本文給大家介紹的非常想詳細(xì)，對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值，需要的朋友可以參考下2023-03-03
Python實(shí)現(xiàn)arctan換算角度的示例
本文主要介紹了Python實(shí)現(xiàn)arctan換算角度的示例，文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2023-03-03
詳解基于Transformer實(shí)現(xiàn)電影評論星級分類任務(wù)
這篇文章主要為大家介紹了詳解基于Transformer實(shí)現(xiàn)電影評論星級分類任務(wù)過程解析，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進(jìn)步，早日升職加薪2023-04-04
Python的CGIHTTPServer交互實(shí)現(xiàn)詳解
本篇文章主要給大家詳細(xì)分析了Python的CGIHTTPServer交互實(shí)現(xiàn)過程以及相關(guān)代碼分享，有興趣的參考學(xué)習(xí)下。2018-02-02
Pygame改編飛機(jī)大戰(zhàn)制作兔子接月餅游戲
一年中秋又快到了，今年加入了Python的學(xué)習(xí)行列，得益于Python的開發(fā)效率和易讀性，網(wǎng)上寫文章的次數(shù)多了起來，既然是中秋節(jié)那肯定要搞個應(yīng)景的游戲才行2022-09-09