Python将源码打包成.whl文件的完整指南

目录

• 一、为什么选择 .whl 文件
• 二、项目结构准备
• 三、现代方式：pyproject.toml 打包
• 1. 安装打包工具
• 2. 配置pyproject.toml
• 3. 构建.whl文件
• 4. 本地安装测试
• 四、传统方式：setup.py打包
• 五、源码保护与加密（可选）
• 方案 1：Cython 编译
• 方案 2：PyArmor 混淆
• 六、总结

Python 项目开发完成后，如何优雅地发布和安装？传统的 python setup.py install 虽然可用，但不够现代化，也不方便在不同环境中快速分发。今天，我们就来详细讲解如何将 Python 源码打包成 .whl 文件（Wheel），并进行安装和分发。

.whl 是 Python 官方推荐的二进制分发格式，相比传统的源码安装有几个优势：

• 快速安装：不需要编译，直接 pip install xxx.whl
• 跨平台（纯 Python）：如果没有 C 扩展，可以在不同操作系统间通用
• 规范标准：兼容现代 Python 打包工具，如 pip 和 build
• 可控依赖：打包时可以指定依赖，安装时自动拉取

假设你的项目名称是 mypkg，最基础的目录结构如下：

mypkg/
├── mypkg/
│   ├── __init__.py
│   └── core.py
├── README.md
├── setup.py        # 传统方式
└── pyproject.toml  # 现代方式推荐

• mypkg/：核心代码
• setup.py：兼容老项目的打包配置
• pyproject.toml：现代标准的打包配置

Python 官方推荐使用 PEP 517/518 标准，通过 pyproject.toml 来描述构建和依赖信息。

pip install build wheel setuptools

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

[project]
name = "mypkg"
version = "0.1.0"
description = "My Python Package"
readme = "README.md"
authors = [
  { name="Your Name", email="you@example.com" }
]
dependencies = []

[tool.setuptools.packages.find]
where = ["."]

在项目根目录执行：

python -m build

生成结果在 dist/ 目录：

dist/
├── mypkg-0.1.0-py3-none-any.whl
└── mypkg-0.1.0.tar.gz

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

对于老项目，如果还在用 setup.py，也可以生成 .whl：

# setup.py
from setuptools import setup, find_packages

setup(
    name="mypkg",
    version="0.1.0",
    packages=find_packages(),
    install_requires=[],
)

构建：

python setup.py bdist_wheel

生成的 .whl 文件同样在 dist/ 目录。

.whl 文件本质上仍然包含源码，如果想防止直接查看 Python 代码，可以考虑：

.py → .pyx → .so / .pyd → 打包成 whl

适合核心逻辑不想暴露的商业项目。

pip install pyarmor
pyarmor gen mypkg/

可以对源码进行混淆，提高反编译成本。

• .whl 是现代 Python 项目的推荐分发格式
• 现代方式使用 pyproject.toml + build，简单快捷
• 传统方式 setup.py 依然可用
• 可选混淆/编译策略保护核心源码

通过打包成 .whl，你可以方便地分发、安装和管理 Python 项目，让用户体验更流畅，也方便 CI/CD 自动化部署。

到此这篇关于Python将源码打包成.whl文件的完整指南的文章就介绍到这了,更多相关Python源码打包内容请搜索风君子博客以前的文章或继续浏览下面的相关文章希望大家以后多多支持风君子博客！

您可能感兴趣的文章:

• python中whl文件封装的实现示例
• 手把手教你打包Python项目为whl文件
• 安装.whl文件(Python Wheel包)的三种方法
• python安装whl包并解决依赖关系的实现
• Python安装本地.whl文件的流程及注意事项
• Python3中.whl文件创建及使用
• python学习之whl文件解释与安装详解