将JupyterNotebook(.ipynb)文件转换为Python(.py)文件的5种方法

在日常数据分析和机器学习开发中，Jupyter Notebook 确实是交互式开发的利器，这点想必大家都有体会。但有些场景下，我们得把它转成纯 Python 脚本（.py）——比如生产环境部署、代码版本管理、团队协作，或是用 Vim 快速改代码。下面整理了 5 种转换方法，从图形界面到命令行、从 IDE 插件到自定义脚本，总有一款能对上你的胃口。

一、为什么要进行转换？

在动手转换之前，不妨先想想：到底什么场景下需要这么做？

二、方法一：使用 Jupyter Notebook 自带功能（最简单）

如果你已经打开了 Notebook，这就是最直截了当的办法。

操作步骤

1. 打开你的 .ipynb 文件
2. 点击顶部菜单栏的 File → Download as → Python (.py)
3. 浏览器自动下载一个 .py 文件到本地

操作示意图

优点

• ✅ 无需安装任何额外工具
• ✅ 零门槛，点几下就行
• ✅ 代码结构保留完好

缺点

• ❌ 必须手动打开 Jupyter
• ❌ 不适合批量转换
• ❌ 没法自定义输出格式

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

nbconvert 是 Jupyter 官方出品的命令行转换工具，功能扎实，批量处理、集成到 CI/CD 都不在话下。

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. 常用参数说明

优点

• ✅ 不用打开浏览器
• ✅ 支持批量转换
• ✅ 能塞进自动化脚本/CI/CD
• ✅ 支持自定义模板

缺点

• ❌ 得记住命令参数
• ❌ 对新手有一丢丢门槛

四、方法三：使用 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')

优点

• ✅ 完全可控，想怎么改就怎么改
• ✅ 能塞进数据处理流水线
• ✅ 可以过滤掉魔法命令、输出结果等无用内容

缺点

• ❌ 得会写代码
• ❌ 某些极端情况下可能处理不完美

五、方法四：使用 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 家族（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)
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 里用了魔法命令（如 %matplotlib inline、%timeit），需要在 .py 里手动删除或替换掉。

Q2: 如何保留 Notebook 中的输出结果？

A: jupyter nbconvert --to script 默认不保留输出。想保留的话，可以用 --to python 加自定义模板，或者先导出成 HTML。

Q3: 转换后的中文注释乱码怎么办？

A: 转换时指定 encoding='utf-8'，并在 .py 文件头部加上 # -*- coding: utf-8 -*- 即可。

Q4: 可以反向转换吗？（.py → .ipynb）

A: 当然可以！用 jupytext 工具：

pip install jupytext
jupytext --to notebook your_script.py

九、总结对比表

十、写在最后

这篇介绍了 5 种将 Jupyter Notebook 转换为 Python 文件的方法，从最简单的界面操作到灵活的脚本自定义，你可以根据手头的场景挑最顺手的那一个。

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