Python 3.6下cx_Freeze打包报错KeyError: 'TCL_LIBRARY'求助

我看到你在用Python 3.6+搭配cx_Freeze打包包含tkinter、matplotlib和Pygame的客户端程序时，遇到了KeyError: 'TCL_LIBRARY'的报错，这个问题在使用虚拟环境打包tkinter程序时很常见——cx_Freeze无法自动识别tkinter依赖的TCL/TK库文件路径，导致构建失败。

报错重现 #

你遇到的完整报错栈如下：

Traceback (most recent call last):
  File "setup.py", line 17, in <module>
    executables = executables
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\dist.py", line 349, in setup
    distutils.core.setup(**attrs)
  File "E:\Python\Lib\distutils\core.py", line 148, in setup
    dist.run_commands()
  File "E:\Python\Lib\distutils\dist.py", line 955, in run_commands
    self.run_command(cmd)
  File "E:\Python\Lib\distutils\dist.py", line 974, in run_command
    cmd_obj.run()
  File "E:\Python\Lib\distutils\command\build.py", line 135, in run
    self.run_command(cmd_name)
  File "E:\Python\Lib\distutils\cmd.py", line 313, in run_command
    self.distribution.run_command(command)
  File "E:\Python\Lib\distutils\dist.py", line 974, in run_command
    cmd_obj.run()
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\dist.py", line 219, in run
    freezer.Freeze()
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\freezer.py", line 616, in Freeze
    self.finder = self._GetModuleFinder()
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\freezer.py", line 342, in _GetModuleFinder
    finder.IncludePackage(name)
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\finder.py", line 659, in IncludePackage
    module = self._ImportModule(name, deferredImports)
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\finder.py", line 311, in _ImportModule
    deferredImports, namespace = namespace)
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\finder.py", line 404, in _InternalImportModule
    parentModule, namespace)
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\finder.py", line 417, in _LoadModule
    namespace)
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\finder.py", line 486, in _LoadPackage
    self._LoadModule(name, fp, path, info, deferredImports, parent)
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\finder.py", line 464, in _LoadModule
    self._RunHook("load", module.name, module)
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\finder.py", line 537, in _RunHook
    method(self, *args)
  File "E:\Projekty\venv\lib\site-packages\cx_Freeze\hooks.py", line 615, in load_tkinter
    tclSourceDir = os.environ["TCL_LIBRARY"]
  File "E:\Projekty\venv\lib\os.py", line 669, in __getitem__
    raise KeyError(key) from None
KeyError: 'TCL_LIBRARY'

解决步骤 #

我们需要手动指定TCL/TK的库路径，并确保相关的DLL文件被打包到构建目录中，修改你的setup.py如下：

1. 添加环境变量配置，让cx_Freeze找到TCL/TK库
2. 更新build_exe选项，包含必要的文件和依赖

修改后的完整setup.py脚本

import cx_Freeze
import sys
import matplotlib
import os

# 手动设置TCL和TK的库路径（适配Python 3.6，版本号根据实际情况调整）
PYTHON_INSTALL_DIR = os.path.dirname(os.path.dirname(os.__file__))
os.environ['TCL_LIBRARY'] = os.path.join(PYTHON_INSTALL_DIR, 'tcl', 'tcl8.6')
os.environ['TK_LIBRARY'] = os.path.join(PYTHON_INSTALL_DIR, 'tcl', 'tk8.6')

base = None
if sys.platform == "win32":
    base = "Win32GUI"

executables = [cx_Freeze.Executable("python.py", base=base)]

cx_Freeze.setup(
    name="music-Client",
    options={
        "build_exe": {
            "packages": ["tkinter", "matplotlib", "Pygame"],
            "includes": ["tkinter"],
            "include_files": [
                os.path.join(PYTHON_INSTALL_DIR, 'DLLs', 'tcl86t.dll'),
                os.path.join(PYTHON_INSTALL_DIR, 'DLLs', 'tk86t.dll')
            ]
        }
    },
    version="1",
    description="hello",
    executables=executables
)

注意事项 #

• 如果你的Python版本不是3.6，需要修改tcl8.6/tk8.6和tcl86t.dll/tk86t.dll的版本号（比如Python 3.9对应tcl8.6，Python 3.11对应tcl8.7）
• 如果你使用的是虚拟环境，PYTHON_INSTALL_DIR可能指向虚拟环境的Python路径，若无法自动识别，可以手动替换为系统Python的安装路径（例如'C:\\Python36'，注意Windows路径的转义）
• 打包matplotlib和Pygame时可能还需要额外配置（比如matplotlib的后端、Pygame的资源文件），解决完TCL问题后如果遇到其他报错，可以针对性调整packages或include_files选项

内容的提问来源于stack exchange，提问作者jan kolář