一、为什么要将Python打包为 exe？

在实际应用中，我们希望Python程序能在没有安装Python环境的电脑上直接运行。将Python代码打包为exe可执行文件，不仅能解决环境依赖问题，还便于程序的分发和部署。

二、常用打包工具及核心函数介绍

1. pyinstaller

pyton程序版本需要Python <3.14, >=3.8。

安装：pip install pyinstaller -i
https://mirrors.aliyun.com/pypi/simple/

打包：pyinstaller [options] script.py

[options]为打包选项，script.py为打包的Python脚本。

• -F：打包成单个可执行文件（推荐使用，方便文件分发）。
• -w：窗口化模式，隐藏命令行窗口（适用于图形界面程序）。
• -i：指定程序图标（格式如.ico）。

案例：

# 打包成单个可执行文件
pyinstaller -F hello.py
# 打包图形界面程序，隐藏命令行窗口并指定图标
pyinstaller -F -w -i icon.ico gui_app.py

当然还有其他一些参数，参见附录中的介绍。

2. cx_Freeze

python版本需要Python >=3.9。

安装：pip install cx_Freeze -i
https://mirrors.aliyun.com/pypi/simple/

打包：需要在项目目录下创建setup.py文件进行配置，然后在命令行执行python setup.py build进行打包，最后在build目录下生成可执行exe文件。

from cx_Freeze import setup, Executable
setup(
name="MyApp",
version="1.0",
description="My Python application",
executables=[Executable("main.py")]
)

3. py2exe

py2exe用于Windows平台，适配python版本：Python < 3.12, >=3.8

安装：pip install py2exe -i
https://mirrors.aliyun.com/pypi/simple/

打包：需要在项目目录下创建setup.py文件进行配置，然后在命令行执行python setup.py py2exe进行打包，最后在当前目录下生成可执行exe文件。

from distutils.core import setup
import py2exe
setup(
console=["main.py"]
)

三、实用案例详解

我们将之前文章介绍的使用pywebio做数学题的web程序打包为一个exe可执行文件。（文章：Python中PyWebIO：无须搞懂前端知识，也能5分钟快速搭建Web应用）

我们新建一个pywebio-math.py文件，放入程序

from pywebio.pin import put_input, pin, pin_wait_change
from pywebio.output import *
from pywebio.input import *
import random
from pywebio.session import hold


class calcMath:

    def __init__(self, num):
        self.num = num  # 题目的数量
        self.finish_switch = False  # 答案提交后 置为True

    def mathproblem(self):
        """
        根据题目的数量，生成100以内的的加减混合运算的数学题的字典并返回；
        字典的key是题目，value是答案
        """
        math_problem = {}
        num = 1
        while num <= self.num:
            num1 = random.randint(1, 99)
            num2 = random.randint(1, 99)
            num3 = random.randint(1, 99)
            if num1 + num2 - num3 < 100 and num1 + num2 - num3 > 0 and num1 + num2 < 100:
                num += 1
                result = num1 + num2 - num3
                key_name = f'{num1} + {num2} - {num3}'
                math_problem[key_name] = result
        return math_problem

    def submit_result(self):
        # 弹出对话框  是否确认提交  点击提交会触发生成答案信息
        popup('确定提交吗？', [
            put_buttons(['确定'], onclick=lambda _: self.set_witch()),
            put_buttons(['取消'], onclick=lambda _: close_popup())
        ])

    def set_witch(self):
        self.finish_switch = True
        try:
            close_popup()
        except Exception as e:
            print(e)

        if self.finish_switch:
            # 生成答案信息 并输出
            self.analyse_result(inputs_str, origin_answer_result, new_answer_result)
            self.finish_switch = False

    def analyse_result(self, inputs_str, origin_answer_result, new_answer_result):

        """
        分析答案
        :param inputs_str: 包含题目信息的列表
        :param origin_answer_result:  真实答案
        :param new_answer_result:     答题的答案
        : return:
        """

        rightnum = 0  # 做对的题目数
        for num in range(len(inputs_str)):
            # 判断输入为空或者不为数字时，认为题目做错了
            if not new_answer_result[num] or not str(new_answer_result[num]).isdigit():
                put_text(
                    f'这个题 {inputs_str[num]} 做错了, 提交的答案是{new_answer_result[num]} ,正确答案是{origin_answer_result[num]}')
            else:
                # 当真实答案和做出的答案一致时，数字加1
                if int(origin_answer_result[num]) == int(new_answer_result[num]):
                    rightnum += 1
                else:
                    put_text(
                        f'这个题 {inputs_str[num]} 做错了, 提交的答案是{new_answer_result[num]} ,正确答案是{origin_answer_result[num]}')
        # 汇总最后的结果输出到web页面上
        put_text(f'--总共{len(inputs_str)}，做对了{rightnum}题，做错了{len(inputs_str) - rightnum}题')

    def start_do_math(self):
        """
        执行函数
        :return:
        """
        # 生成数学题字典 key是题目，value是答案
        mathdict = self.mathproblem()

        # 生成pywebio的input函数用到的输入数学题信息列表： 展示的是题目信息
        inputs_str = [f'{key} = ( )' for key in mathdict.keys()]

        # 生成对应的答案列表 用于跟答题时写的答案做对比
        origin_answer_result = [mathdict[key] for key in mathdict.keys()]

        # 调用pywebio的pin.put_input函数 和pin_wait_change 监听输入的答案 输入后进行下一个题目
        keys = [f'num{i + 1}' for i in range(self.num)]
        for i in range(self.num):
            put_input(keys[i], label=f'第{i + 1}题 请在下方输入答案（输入后不支持修改）\n {inputs_str[i]}')
            pin_wait_change(keys[i], timeout=1000)  # 监听输入 有输入后才进行下一次循环

        # 提交按钮  点击后弹出确认对话框
        put_button('submit', onclick=self.submit_result)
        # 提取提交的答案
        new_answer_result = [getattr(pin, key) for key in keys]
        # print(new_answer_result)
        return inputs_str, origin_answer_result, new_answer_result


num = input('请输入题目的数量：',type=NUMBER)
math1 = calcMath(num)  #实例化
inputs_str, origin_answer_result, new_answer_result = math1.start_do_math()
#保持会话 直到关闭浏览器
hold()

然后我们使用上述介绍的方法，打包为一个exe文件，打包后我们双击exe文件，执行效果跟通过python执行是一样的。

我们使用cx_Freeze进行打包，在程序目录中见一个setup.py文件，然后填入参数

from cx_Freeze import setup, Executable
setup(
    name="MyApp",
    version="1.0",
    description="My Python application",
    executables=[Executable("pywebio-math.py")]
)

目录内容如下：

然后再命令行执行：

最后在build目录生成一个exe文件

我们双击pywebio-math.exe然后执行。

四、附录

pyinstaller的其他一些参数介绍：

1. -p, --paths 添加额外的模块搜索路径。当你的程序依赖的模块不在默认搜索路径中时，可通过该参数指定路径，让PyInstaller找到相关模块。

pyinstaller -F -p ./my_lib script.py

这样PyInstaller在打包时就会到./my_lib路径下查找所需模块。

2. --add-data 将非 Python 文件（如图片、配置文件等）添加到打包结果中。在 Windows 系统中，参数格式为source;dest；在 Linux 和 macOS 系统中，参数格式为source:dest。其中source是源文件或目录路径，dest是打包后文件在可执行文件中的存放路径。

若你的程序使用了icon.png图片，且该图片在./images目录下，希望打包后图片存放在./assets目录下，在 Linux 或 macOS 系统中可使用以下命令：

pyinstaller -F --add-data "images/icon.png:assets" script.py

在 Windows 系统中则为：

pyinstaller -F --add-data "images/icon.png;assets" script.py

3. --exclude-data-dir 从打包结果中排除指定的数据目录，可用于减少打包文件体积，排除不必要的数据。

如果你的项目中./temp_data目录下的数据在程序运行时不需要，可使用该参数排除：

pyinstaller -F --exclude-data-dir temp_data script.py

4. -D, --onedir 将程序打包成一个目录，目录中包含可执行文件和所有依赖文件。相比-F生成单个可执行文件，这种模式便于调试和查看文件结构。

pyinstaller -D script.py

打包完成后，在dist目录下会生成一个以脚本名称命名的文件夹，里面存放着可执行文件和相关依赖。

5. --clean 在打包前清理掉之前打包过程中产生的临时文件和缓存，避免旧的打包残留影响本次打包，确保打包的纯净性。

pyinstaller --clean -F script.py

6. --upx-dir 指定UPX压缩工具的路径。UPX 是一款高效的可执行文件压缩器，使用--upx-dir参数并配合--upx-exclude等参数，可以压缩打包后的可执行文件，减小文件体积。

pyinstaller --upx-dir /usr/local/upx -F your_script.py

7. --debug 启用调试模式，可分为--debug=imports、--debug=bootloader等不同级别。--debug=imports会在打包过程中输出详细的模块导入信息，有助于排查模块导入相关问题；--debug=bootloader则输出引导加载器相关的调试信息。

pyinstaller --debug=imports -F script.py