如何将包含ipywidgets的ipynb文件转换为可执行程序？

问题原因 #

ipywidgets原本是为Jupyter Notebook/Lab设计的交互组件，依赖Jupyter的前端渲染环境与内核交互机制。直接用PyInstaller打包普通脚本时，缺少必要的前端渲染支撑，导致GUI元素无法显示，仅能执行纯Python逻辑（比如print语句）。

可行解决方案 #

方案1：使用Voilà打包（推荐） #

Voilà是专门将Jupyter Notebook转为独立Web应用的工具，完美兼容ipywidgets，且支持打包为可执行程序。

步骤：

1. 安装依赖工具：

   pip install voila pyinstaller
   

2. 打包Notebook为独立exe：
   • 先生成Voilà独立应用结构：

     voila --standalone --enable_nbextensions=True test.ipynb --output=test_app
     

   • 进入生成的目录，用PyInstaller打包：

     cd test_app
     pyinstaller --onefile voila_standalone.py
     

   运行dist目录下的exe时，会启动本地Web服务器，在浏览器中加载包含ipywidgets的完整UI界面。

方案2：替换为原生桌面GUI库（适合纯桌面应用） #

如果不需要Web交互形式，可将ipywidgets替换为PyQt、Tkinter等原生桌面GUI库，PyInstaller能正常打包这类脚本。

示例（用Tkinter改写你的代码）：

import tkinter as tk

def on_run_click():
    print("Run button clicked")

root = tk.Tk()
root.title("Test App")
run_button = tk.Button(root, text="Run", command=on_run_click)
run_button.pack(pady=20)

print("hello world")
root.mainloop()

打包命令：

pyinstaller --onefile --windowed test.py

--windowed参数可隐藏控制台窗口，仅显示GUI界面。

方案3：用PyWebView嵌入ipywidgets界面 #

利用PyWebView将ipywidgets的Web界面嵌入桌面窗口，无需依赖外部浏览器。

步骤：

1. 安装依赖：

   pip install ipywidgets pywebview
   

2. 改写脚本，将ipywidgets转为HTML并通过PyWebView加载：

   import ipywidgets as widgets
   from ipywidgets import VBox, Output
   import webview
   
   run_button = widgets.Button(description="Run", disabled=False)
   output = widgets.Output()
   
   def on_run_click(b):
       with output:
           print("Run button clicked")
   
   run_button.on_click(on_run_click)
   ui = VBox([run_button, output])
   
   # 将ipywidgets组件转为HTML
   html = ui._repr_html_()
   full_html = f"""
   <html>
   <head>
       <script src="https://cdn.jsdelivr.net/npm/@jupyter-widgets/html-manager@^1.0.0/dist/embed-amd.js"></script>
   </head>
   <body>
       {html}
   </body>
   </html>
   """
   
   print("hello world")
   webview.create_window("Test App", html=full_html)
   webview.start()
   

3. 打包命令：

   pyinstaller --onefile --windowed test.py
   

   注：首次运行需联网加载前端依赖，若要离线使用，可通过PyInstaller的--add-data参数将相关JS文件打包进程序。

总结 #

• 优先选Voilà，适配ipywidgets原有逻辑，无需大量改写代码；
• 纯桌面需求下，替换为原生GUI库更稳定；
• PyWebView适合需要桌面嵌入Web界面的场景。

内容的提问来源于stack exchange，提问作者tanman81