Jupyter Notebook（ipynb）转 Python（py）文件

Jupyter Notebook（ipynb）转 Python（py）文件：从环境准备到问题解决

在数据科学、机器学习或 Python 开发中，Jupyter Notebook（.ipynb文件）是常用的交互式开发工具，但实际部署或代码分享时，常需要将其转换为可直接运行的 Python 脚本（.py文件）。本文基于nbconvert工具，详细讲解转换流程、常见问题及解决方案，适用于 Windows 环境，新手也能轻松上手。

一、先决条件：环境准备

在开始转换前，需确保本地环境满足以下条件，避免后续报错：

1. 基础环境

Python 环境 ：已安装 Python 3.8+（推荐 3.10+，兼容性更好），可通过python --version或py --version在命令行验证。
虚拟环境（可选但强烈推荐） ：建议使用虚拟环境隔离项目依赖（如venv、conda），避免包版本冲突。本文以venv创建的虚拟环境为例（路径：D:\Development_tools\python_venv）。

2. 核心依赖包

转换依赖nbconvert（Jupyter 官方转换工具），需确保已安装。检查与安装命令如下：

步骤 1：激活虚拟环境（若使用）

Windows 系统激活命令：

bash 复制代码

# 进入虚拟环境的Scripts目录
cd D:\Development_tools\python_venv\Scripts

# 激活虚拟环境（激活后命令行前缀会显示"(python_venv)"）
activate

步骤 2：检查并安装`nbconvert`

bash 复制代码

# 检查是否已安装nbconvert
pip list | findstr "nbconvert"

# 若未安装，执行以下命令安装（版本7.x+均可）
pip install nbconvert --upgrade

二、标准流程：ipynb 转 py 文件（3 步完成）

基于nbconvert的官方用法（参考nbconvert 文档），转换仅需 3 步，无额外依赖。

步骤 1：进入目标文件目录

在命令行中，切换到.ipynb文件所在的文件夹。例如本文示例路径：

bash 复制代码

# 切换到代码目录（根据你的实际路径修改）
cd E:\代码

步骤 2：执行转换命令

核心命令格式：

bash 复制代码

jupyter nbconvert --to script 文件名.ipynb

本文示例（转换第5次课.ipynb）：

bash 复制代码

jupyter nbconvert --to script 第5次课.ipynb

步骤 3：验证转换结果

若成功，命令行无报错，且在当前目录生成第5次课.py文件。
打开第5次课.py，可看到 Notebook 中的代码块被保留（注释会标注单元格类型），可直接用 Python 运行。

三、常见问题与解决方案

实际操作中，常因包兼容性 或配置残留导致转换失败。以下是两个高频问题的完整解决流程（基于真实报错案例）。

问题 1：ModuleNotFoundError: No module named 'notebook.services'

报错现象

执行转换命令后，提示缺少notebook.services模块，日志关键信息：

plaintext 复制代码

File "D:\...\jupyter_contrib_nbextensions\nbconvert_support\collapsible_headings.py", line 6, in <module>
    from notebook.services.config import ConfigManager
ModuleNotFoundError: No module named 'notebook.services'

问题根源

jupyter_contrib_nbextensions（Jupyter 扩展工具）与notebook 7.x版本不兼容：notebook 7.x基于 JupyterLab 重构，删除了notebook.services等旧版模块，而jupyter_contrib_nbextensions仅适配notebook 6.x。
该扩展并非转换ipynb到py的必需依赖，仅用于增强 Notebook 界面功能（如折叠标题）。

解决方案：卸载冲突扩展

确保已激活虚拟环境（命令行前缀显示(python_venv)）。

执行卸载命令：

bash 复制代码

pip uninstall -y jupyter_contrib_nbextensions

卸载完成后，重新执行转换命令（通常可解决问题；若仍报错，需处理配置残留，见问题 2）。

问题 2：ModuleNotFoundError: No module named 'jupyter_contrib_nbextensions'（卸载后仍报错）

报错现象

卸载jupyter_contrib_nbextensions后，执行转换命令仍提示缺少该模块，日志关键信息：

plaintext 复制代码

File "D:\...\nbconvert\exporters\exporter.py", line 253, in register_preprocessor
    preprocessor_cls = import_item(preprocessor)
ModuleNotFoundError: No module named 'jupyter_contrib_nbextensions'

问题根源

卸载扩展时，其向nbconvert配置文件中添加的「预处理器（Preprocessor）」配置未被自动清理。
nbconvert启动时会读取旧配置，试图加载已删除的扩展模块，导致报错。

解决方案：清理残留配置

需手动删除 Jupyter/nbconvert 配置文件中的残留内容，步骤如下：

步骤 1：找到 Jupyter 配置目录

Windows 系统中，配置目录路径固定为：

plaintext 复制代码

C:\Users\你的用户名\.jupyter

示例：若用户名为Z1501，路径为C:\Users\Z1501\.jupyter。
若看不到.jupyter文件夹，需开启「显示隐藏项目」（文件夹顶部「查看」选项卡中勾选）。

步骤 2：删除 / 修改残留配置文件

在.jupyter目录中，按优先级检查以下文件，删除涉及jupyter_contrib_nbextensions的内容：

优先处理nbconvert_config.py（nbconvert 专属配置）

用记事本 / VS Code 打开该文件（若不存在则跳过）。

搜索包含

复制代码

jupyter_contrib_nbextensions

的行，典型残留配置如下：

python 复制代码

# 示例残留内容（格式可能不同，核心是包含该扩展路径）
c.Exporter.preprocessors = [
    'jupyter_contrib_nbextensions.nbconvert_support.collapsible_headings.CollapsibleHeadingsPreprocessor',
    'jupyter_contrib_nbextensions.nbconvert_support.other_preprocessor'
]

删除上述包含该扩展的配置行 （或在每行前加#注释），保存文件。

其次处理jupyter_config.py（Jupyter 全局配置）
- 打开该文件，同样搜索jupyter_contrib_nbextensions，删除所有相关配置，保存文件。
最后处理nbconfig子目录
- 若仍报错，进入.jupyter\nbconfig目录，删除notebook.json或nbconvert.json中涉及该扩展的内容（或直接重命名nbconfig为nbconfig_backup，临时禁用所有扩展配置）。

步骤 3：临时应急方案（若找不到配置文件）

若暂时无法定位配置文件，可在转换命令中强制清空预处理器列表，规避残留配置：

bash 复制代码

jupyter nbconvert --to script 第5次课.ipynb --Exporter.preprocessors=[]

四、验证与测试

转换完成后，需确认结果是否正确：

检查文件生成 ：在.ipynb文件所在目录，确认是否生成第5次课.py文件。
验证文件内容 ：打开第5次课.py，检查代码块是否完整（Notebook 中的代码会保留，注释会标注单元格类型）。
测试脚本运行 ：在命令行中执行python 第5次课.py，确认脚本可正常运行（无语法错误）。

五、注意事项

始终激活虚拟环境：若使用虚拟环境，所有操作（安装包、转换文件）需在激活状态下执行，避免依赖安装到全局环境。
备份配置文件 ：修改.jupyter目录下的配置文件前，建议先复制备份（避免误删导致其他问题）。
避免不必要的扩展 ：仅安装必需的包（如nbconvert），减少jupyter_contrib_nbextensions等非必需扩展，降低兼容性风险。
版本兼容性 ：若需使用notebook 7.x，建议避免安装jupyter_contrib_nbextensions；若需该扩展，可降级notebook到6.x（命令：pip install notebook==6.5.6）。

六、结语

本文详细讲解了ipynb转py文件的标准流程及两类高频问题的解决方案。核心总结：

转换的核心工具是nbconvert，标准命令仅需jupyter nbconvert --to script 文件名.ipynb。
常见报错多源于扩展兼容性或配置残留，卸载冲突扩展 + 清理配置即可解决。
主要采用

bash 复制代码

jupyter nbconvert --to script 第5次课.ipynb --Exporter.preprocessors=[]

若在操作中遇到其他问题，可通过jupyter nbconvert --help查看官方帮助，或留言讨论。

Jupyter Notebook（ipynb）转 Python（py）文件