如何将 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，这是最直接、最简单的方法。

操作步骤

1. 打开 你的 Jupyter Notebook 文件（.ipynb）
2. 点击顶部菜单栏的 File → Download as → Python (.py)
3. 浏览器会自动下载转换后的 .py 文件到本地

操作示意图

优点

• ✅ 无需安装额外工具
• ✅ 一键操作，零门槛
• ✅ 保留代码结构

缺点

• ❌ 需要手动打开 Jupyter Notebook
• ❌ 不适合批量转换
• ❌ 无法自定义输出格式

---

三、方法二：使用命令行工具 jupyter nbconvert（推荐）

nbconvert 是 Jupyter 官方提供的命令行转换工具，功能强大，支持批量转换和多种格式。

1. 安装 Jupyter（如未安装）

pip install jupyter

或安装 nbconvert 独立包：

pip install nbconvert

2. 基本转换命令

打开终端（Windows 使用 CMD / PowerShell，macOS/Linux 使用 Terminal），进入 .ipynb 文件所在目录，执行：

jupyter nbconvert --to script your_notebook.ipynb

示例：

# 进入文件目录
cd D:\Projects\MyProject

# 执行转换
jupyter nbconvert --to script data_analysis.ipynb

3. 终端输出示例

[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):

for file in *.ipynb; do jupyter nbconvert --to script "$file"; done

5. 常用参数说明

参数	说明	示例
--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 脚本实现。

基础版本：仅提取代码单元格

import json

def convert_ipynb_to_py(ipynb_file, py_file):
    """
    将 Jupyter Notebook 文件转换为 Python 脚本文件
    
    参数:
        ipynb_file: 输入的 .ipynb 文件路径
        py_file: 输出的 .py 文件路径
    """
    # 读取 .ipynb 文件（JSON 格式）
    with open(ipynb_file, 'r', encoding='utf-8') as f:
        notebook = json.load(f)
    
    # 写入 .py 文件
    with open(py_file, 'w', encoding='utf-8') as f:
        for cell in notebook['cells']:
            # 只提取 code 类型的单元格
            if cell['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 注释 + 过滤魔法命令

import json
import re

def convert_ipynb_to_py_advanced(ipynb_file, py_file):
    """
    高级转换：保留 Markdown 作为注释，过滤 Jupyter 魔法命令
    """
    with open(ipynb_file, 'r', encoding='utf-8') as f:
        notebook = json.load(f)
    
    with open(py_file, 'w', encoding='utf-8') as f:
        # 写入文件头
        f.write('# -*- coding: utf-8 -*-\n')
        f.write(f'# Converted from: {ipynb_file}\n')
        f.write('# ============================================\n\n')
        
        for i, cell in enumerate(notebook['cells']):
            if cell['cell_type'] == 'markdown':
                # 将 Markdown 转换为 Python 注释
                source = ''.join(cell['source'])
                comment_lines = ['# ' + line for line in source.split('\n')]
                f.write('\n'.join(comment_lines) + '\n\n')
                
            elif cell['cell_type'] == 'code':
                source = ''.join(cell['source'])
                
                # 过滤 Jupyter 魔法命令（如 %matplotlib inline）
                lines = source.split('\n')
                filtered_lines = []
                for line in lines:
                    if not line.strip().startswith('%') and not line.strip().startswith('!'):
                        filtered_lines.append(line)
                
                if filtered_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 进行开发，可以通过插件实现一键转换。

操作步骤

1. 安装 Jupyter 插件

   • 打开 VS Code
   • 进入扩展商店（Ctrl+Shift+X）
   • 搜索并安装 Jupyter（Microsoft 官方插件）

2. 打开 .ipynb 文件

   • 在 VS Code 中打开你的 Notebook 文件

3. 导出为 Python 脚本

   • 点击右上角的 ...（更多操作）
   • 选择 Export → Python Script
   • 选择保存位置即可

优点

• ✅ 集成在开发环境中，无需切换
• ✅ 可视化操作
• ✅ 支持调试 Notebook 后直接导出

缺点

• ❌ 需要安装 VS Code 和插件
• ❌ 不适合服务器环境

---

六、方法五：使用 PyCharm / DataSpell（JetBrains 用户）

如果你使用 JetBrains 系列的 IDE（如 PyCharm Professional 或 DataSpell），也支持直接导出。

操作步骤

1. 打开 .ipynb 文件

   • 在 PyCharm 中打开 Notebook 文件

2. 导出操作

   • 点击 Notebook 工具栏上的 Convert to Python File 按钮
   • 或右键点击文件 → Export to Python File

优点

• ✅ 与 IDE 深度集成
• ✅ 可保持代码结构清晰

缺点

• ❌ 仅 PyCharm Professional / DataSpell 支持
• ❌ 社区版（Community）不支持

---

七、转换效果对比

假设我们有如下 Notebook 内容：

# Cell 1 (Markdown)
# ## 数据分析示例

# Cell 2 (Code)
import pandas as pd
import matplotlib.pyplot as plt

# 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
# ============================================

# ## 数据分析示例

import pandas as pd
import matplotlib.pyplot as plt

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 工具：

pip install jupytext
jupytext --to notebook your_script.py

---

九、总结对比表

方法	难度	适用场景	批量转换	自定义
Jupyter 界面下载	⭐ 简单	偶尔转换	❌	❌
jupyter nbconvert 命令	⭐⭐ 中等	日常开发、批量处理	✅	✅
Python 脚本自定义	⭐⭐⭐ 较难	特殊需求、自动化	✅	✅✅✅
VS Code 导出	⭐ 简单	VS Code 用户	❌	❌
PyCharm / DataSpell	⭐ 简单	JetBrains 用户	❌	❌

---

十、写在最后

本文介绍了 5 种将 Jupyter Notebook 转换为 Python 文件的方法，从最简单的界面操作到灵活的脚本自定义，你可以根据自己的需求选择最合适的方式。

💡 个人建议 ：日常使用推荐 方法二（命令行） ，简单高效；有特殊需求时选择 方法三（Python 脚本） 进行自定义处理。

如果这篇文章对你有帮助，欢迎 点赞 👍、收藏 ⭐、评论 💬，你的支持是我创作的动力！如有任何问题，欢迎在评论区留言交流。