如何将 Jupyter Notebook (.ipynb) 文件转换为 Python (.py) 文件
摘要：在日常数据分析和机器学习开发中，Jupyter Notebook 是一个非常好用的交互式开发工具。但在某些场景下，我们需要将
.ipynb文件转换为纯 Python 脚本文件（.py），以便于生产环境部署、代码版本管理或与其他开发者协作。本文将详细介绍5 种将 Jupyter Notebook 转换为 Python 文件的方法，涵盖图形界面、命令行、Python 脚本、IDE 工具等多种方式，总有一种适合你！
一、为什么要进行转换？
在正式开始之前，我们先来了解一下为什么需要将.ipynb转换为.py：
| 场景 | 说明 |
|---|---|
| 生产环境部署 | Jupyter Notebook 不适合直接在生产服务器上运行，转换为.py后可以方便地部署和调度 |
| 代码版本管理 | .ipynb文件包含大量 JSON 元数据，Git diff 难以阅读，.py文件更利于代码审查 |
| 团队协作 | 部分团队成员更习惯使用 PyCharm、VS Code 等 IDE 开发纯 Python 文件 |
| 纯文本编辑 | 有时需要在 Vim、Nano 等终端编辑器中快速查看或修改代码 |
| 模块化开发 | 将 Notebook 中的代码整理为可复用的 Python 模块 |
二、方法一：使用 Jupyter Notebook 自带功能（最简单）
如果你已经安装并打开了 Jupyter Notebook，这是最直接、最简单的方法。
操作步骤
- 打开你的 Jupyter Notebook 文件（
.ipynb） - 点击顶部菜单栏的File→Download as→Python (.py)
- 浏览器会自动下载转换后的
.py文件到本地
操作示意图
优点
- ✅ 无需安装额外工具
- ✅ 一键操作，零门槛
- ✅ 保留代码结构
缺点
- ❌ 需要手动打开 Jupyter Notebook
- ❌ 不适合批量转换
- ❌ 无法自定义输出格式
三、方法二：使用命令行工具jupyter nbconvert（推荐）
nbconvert是 Jupyter 官方提供的命令行转换工具，功能强大，支持批量转换和多种格式。
1. 安装 Jupyter（如未安装）
pipinstalljupyter或安装nbconvert独立包：
pipinstallnbconvert2. 基本转换命令
打开终端（Windows 使用 CMD / PowerShell，macOS/Linux 使用 Terminal），进入.ipynb文件所在目录，执行：
jupyter nbconvert--toscript your_notebook.ipynb示例：
# 进入文件目录cdD:\Projects\MyProject# 执行转换jupyter nbconvert--toscript data_analysis.ipynb3. 终端输出示例
[NbConvertApp] Converting notebook data_analysis.ipynb to script [NbConvertApp] Writing 15170 bytes to data_analysis.py转换成功后，你会在同级目录下看到生成的data_analysis.py文件。
4. 批量转换多个文件
如果需要一次性转换目录下的所有.ipynb文件：
Windows (PowerShell):
Get-ChildItem*.ipynb|ForEach-Object{jupyter nbconvert--to script$_.Name}macOS / Linux (Bash):
forfilein*.ipynb;dojupyter nbconvert--toscript"$file";done5. 常用参数说明
| 参数 | 说明 | 示例 |
|---|---|---|
--to script | 转换为 Python 脚本 | jupyter nbconvert --to script file.ipynb |
--to python | 同上（script 的别名） | jupyter nbconvert --to python file.ipynb |
--output | 指定输出文件名 | jupyter nbconvert --to script file.ipynb --output myscript |
--stdout | 输出到标准输出（不保存文件） | jupyter nbconvert --to script file.ipynb --stdout |
--template | 使用自定义模板 | jupyter nbconvert --to script file.ipynb --template full |
优点
- ✅ 无需打开浏览器
- ✅ 支持批量转换
- ✅ 可集成到自动化脚本 / CI/CD 流程
- ✅ 支持自定义模板
缺点
- ❌ 需要记住命令
- ❌ 对新手有一定门槛
四、方法三：使用 Python 脚本自定义转换
如果你需要在转换过程中进行自定义处理（例如过滤特定单元格、添加文件头注释等），可以编写 Python 脚本实现。
基础版本：仅提取代码单元格
importjsondefconvert_ipynb_to_py(ipynb_file,py_file):""" 将 Jupyter Notebook 文件转换为 Python 脚本文件 参数: ipynb_file: 输入的 .ipynb 文件路径 py_file: 输出的 .py 文件路径 """# 读取 .ipynb 文件（JSON 格式）withopen(ipynb_file,'r',encoding='utf-8')asf:notebook=json.load(f)# 写入 .py 文件withopen(py_file,'w',encoding='utf-8')asf:forcellinnotebook['cells']:# 只提取 code 类型的单元格ifcell['cell_type']=='code':# 将 source 列表拼接为字符串source=''.join(cell['source'])f.write(source+'\n\n')# 使用示例if__name__=="__main__":convert_ipynb_to_py('your_notebook.ipynb','your_notebook.py')print("转换完成！")进阶版本：保留 Markdown 注释 + 过滤魔法命令
importjsonimportredefconvert_ipynb_to_py_advanced(ipynb_file,py_file):""" 高级转换：保留 Markdown 作为注释，过滤 Jupyter 魔法命令 """withopen(ipynb_file,'r',encoding='utf-8')asf:notebook=json.load(f)withopen(py_file,'w',encoding='utf-8')asf:# 写入文件头f.write('# -*- coding: utf-8 -*-\n')f.write(f'# Converted from:{ipynb_file}\n')f.write('# ============================================\n\n')fori,cellinenumerate(notebook['cells']):ifcell['cell_type']=='markdown':# 将 Markdown 转换为 Python 注释source=''.join(cell['source'])comment_lines=['# '+lineforlineinsource.split('\n')]f.write('\n'.join(comment_lines)+'\n\n')elifcell['cell_type']=='code':source=''.join(cell['source'])# 过滤 Jupyter 魔法命令（如 %matplotlib inline）lines=source.split('\n')filtered_lines=[]forlineinlines:ifnotline.strip().startswith('%')andnotline.strip().startswith('!'):filtered_lines.append(line)iffiltered_lines:f.write('\n'.join(filtered_lines)+'\n\n')# 使用示例convert_ipynb_to_py_advanced('data_analysis.ipynb','data_analysis_clean.py')优点
- ✅ 完全可控，可自定义转换逻辑
- ✅ 可集成到数据处理流水线
- ✅ 可过滤不需要的内容（如魔法命令、输出结果）
缺点
- ❌ 需要编写代码
- ❌ 可能无法完美处理所有 Notebook 特性
五、方法四：使用 VS Code 插件（开发者友好）
如果你使用Visual Studio Code进行开发，可以通过插件实现一键转换。
操作步骤
安装 Jupyter 插件
- 打开 VS Code
- 进入扩展商店（Ctrl+Shift+X）
- 搜索并安装Jupyter（Microsoft 官方插件）
打开 .ipynb 文件
- 在 VS Code 中打开你的 Notebook 文件
导出为 Python 脚本
- 点击右上角的…（更多操作）
- 选择Export→Python Script
- 选择保存位置即可
优点
- ✅ 集成在开发环境中，无需切换
- ✅ 可视化操作
- ✅ 支持调试 Notebook 后直接导出
缺点
- ❌ 需要安装 VS Code 和插件
- ❌ 不适合服务器环境
六、方法五：使用 PyCharm / DataSpell（JetBrains 用户）
如果你使用 JetBrains 系列的 IDE（如 PyCharm Professional 或 DataSpell），也支持直接导出。
操作步骤
打开 .ipynb 文件
- 在 PyCharm 中打开 Notebook 文件
导出操作
- 点击 Notebook 工具栏上的Convert to Python File按钮
- 或右键点击文件 →Export to Python File
优点
- ✅ 与 IDE 深度集成
- ✅ 可保持代码结构清晰
缺点
- ❌ 仅 PyCharm Professional / DataSpell 支持
- ❌ 社区版（Community）不支持
七、转换效果对比
假设我们有如下 Notebook 内容：
# Cell 1 (Markdown)# ## 数据分析示例# Cell 2 (Code)importpandasaspdimportmatplotlib.pyplotasplt# Cell 3 (Code)%matplotlib inline df=pd.read_csv('data.csv')df.head()# Cell 4 (Code)plt.plot(df['x'],df['y'])plt.show()转换后的.py文件（方法三进阶版）
# -*- coding: utf-8 -*-# Converted from: analysis.ipynb# ============================================# ## 数据分析示例importpandasaspdimportmatplotlib.pyplotasplt df=pd.read_csv('data.csv')df.head()plt.plot(df['x'],df['y'])plt.show()八、常见问题 FAQ
Q1: 转换后的.py文件能直接运行吗？
A:大部分情况下可以直接运行，但如果 Notebook 中使用了 Jupyter 魔法命令（如%matplotlib inline、%timeit），需要在.py中删除或替换这些命令。
Q2: 如何保留 Notebook 中的输出结果？
A:jupyter nbconvert --to script默认不保留输出。如需保留，建议使用--to python配合自定义模板，或使用jupyter nbconvert --to html先导出为 HTML。
Q3: 转换后的中文注释乱码怎么办？
A:确保转换时指定encoding='utf-8'，并在.py文件头部添加# -*- coding: utf-8 -*-。
Q4: 可以反向转换吗？（.py → .ipynb）
A:可以！使用jupytext工具：
pipinstalljupytext jupytext--tonotebook your_script.py九、总结对比表
| 方法 | 难度 | 适用场景 | 批量转换 | 自定义 |
|---|---|---|---|---|
| Jupyter 界面下载 | ⭐ 简单 | 偶尔转换 | ❌ | ❌ |
jupyter nbconvert命令 | ⭐⭐ 中等 | 日常开发、批量处理 | ✅ | ✅ |
| Python 脚本自定义 | ⭐⭐⭐ 较难 | 特殊需求、自动化 | ✅ | ✅✅✅ |
| VS Code 导出 | ⭐ 简单 | VS Code 用户 | ❌ | ❌ |
| PyCharm / DataSpell | ⭐ 简单 | JetBrains 用户 | ❌ | ❌ |
十、写在最后
本文介绍了5 种将 Jupyter Notebook 转换为 Python 文件的方法，从最简单的界面操作到灵活的脚本自定义，你可以根据自己的需求选择最合适的方式。
💡个人建议：日常使用推荐方法二（命令行），简单高效；有特殊需求时选择方法三（Python 脚本）进行自定义处理。
如果这篇文章对你有帮助，欢迎点赞 👍、收藏 ⭐、评论 💬，你的支持是我创作的动力！如有任何问题，欢迎在评论区留言交流。