无法将使用python-docx的Python脚本转换为.exe文件

阿华AIGC实验室

2026-5-20

解决Python脚本打包exe时docx库导致的问题

这种情况我之前也碰到过！核心问题是python-docx依赖自带的模板文件，而打包工具默认不会把这些非代码的资源文件包含进去，导致exe运行时找不到必要的文件，要么报错要么直接闪退。下面分工具给你具体的解决办法，还有排查技巧：

一、先排查最常见的闪退原因（PyInstaller用户优先看）

PyInstaller闪退大概率是因为控制台被隐藏了，看不到错误信息。先去掉--windowed参数，用控制台模式打包运行：

pyinstaller --onefile your_script.py

运行生成的exe，控制台里会显示具体的错误（比如FileNotFoundError: [Errno 2] No such file or directory: .../docx/templates/default.docx），这就能确认是模板文件缺失的问题。

PyInstaller的完整解决步骤

自动收集docx资源：用--collect-data参数让PyInstaller自动打包docx的所有资源文件：

pyinstaller --onefile --windowed --collect-data python-docx your_script.py

手动指定资源路径（备选）：如果自动收集不行，就手动处理路径。在你的脚本里加一个获取资源路径的函数，适配开发和打包后的环境：

from docx import Document
import os
import sys

def resource_path(relative_path):
    """获取资源的绝对路径，兼容开发环境和打包后的exe"""
    try:
        # PyInstaller打包后会把资源放到临时目录sys._MEIPASS
        base_path = sys._MEIPASS
    except Exception:
        # 开发环境下用当前脚本的目录
        base_path = os.path.abspath(".")
    return os.path.join(base_path, relative_path)

# 用上面的函数加载docx模板
doc_template = resource_path(os.path.join('docx', 'templates', 'default.docx'))
doc = Document(doc_template)

然后打包时用--add-data参数把模板文件加进去（Windows用分号分隔路径，Mac/Linux用冒号）：

pyinstaller --onefile --windowed --add-data "C:/Python36/Lib/site-packages/docx/templates/default.docx;docx/templates" your_script.py

（注意把路径换成你自己的python-docx安装路径）

二、cx_Freeze的解决办法

cx_Freeze需要在setup.py里明确指定要包含的docx模板目录，示例配置如下：

import sys
from cx_Freeze import setup, Executable
import docx
import os

# 获取docx模板文件所在的目录
docx_templates_dir = os.path.join(os.path.dirname(docx.__file__), 'templates')

# 配置打包参数
setup(
    name="你的应用名称",
    version="1.0",
    description="应用描述",
    # 指定要打包的脚本，base="Win32GUI"隐藏控制台
    executables=[Executable("your_script.py", base="Win32GUI")],
    options={
        "build_exe": {
            # 把docx模板目录复制到打包后的docx/templates下
            "include_files": [(docx_templates_dir, "docx/templates")],
            # 明确包含docx库
            "packages": ["docx"],
        }
    }
)

然后运行python setup.py build完成打包。

三、py2exe的解决办法

py2exe需要在setup.py的data_files里添加docx的模板文件，示例配置：

from distutils.core import setup
import py2exe
import docx
import os

# 获取docx模板目录和所有模板文件
docx_templates_dir = os.path.join(os.path.dirname(docx.__file__), 'templates')
template_files = [(os.path.join('docx', 'templates'), 
                   [os.path.join(docx_templates_dir, f) for f in os.listdir(docx_templates_dir)])]

setup(
    # windows参数指定打包成窗口程序，隐藏控制台
    windows=['your_script.py'],
    # 添加模板文件到打包后的目录
    data_files=template_files,
    options={
        "py2exe": {
            # 明确包含docx库
            "includes": ["docx"],
        }
    }
)

运行python setup.py py2exe即可生成exe。