1. 引言：为什么需要 Jupyter Notebook？

Jupyter Notebook 已经成为数据科学、机器学习、科学计算以及教学领域的事实标准。它结合了代码执行、富文本展示、可视化图形和数学公式于一体，创造了“可执行文档”的概念。截至 2025 年，Jupyter 生态系统拥有超过千万用户，GitHub 上托管的 .ipynb 文件数量以亿计。

1.1 核心优势

  • 交互式探索：逐单元格执行，即时查看结果，非常适合数据分析。

  • 文档与代码并存：可以使用 Markdown 记录思路，嵌入 LaTeX 公式，生成可复现的报告。

  • 多语言支持：通过内核支持 Python、R、Julia、Scala 等超过 100 种语言。

  • 可视化友好：原生支持 Matplotlib、Plotly、Altair 等图表库，图表直接内嵌。

  • 教学与分享：教师可编写带有练习的 Notebook，学生执行并提交；研究成果可通过 Binder 一键复现。

1.2 适用场景

场景 典型应用
数据清洗与探索 使用 pandas 逐步探索数据集，可视化分布
机器学习建模 训练模型，调参，评估指标，可视化学习曲线
学术研究 记录实验过程，生成论文中的图表，补充材料
教学 编写交互式教程，自动评分
报告与仪表盘 生成定时更新的报告（配合 Papermill）

2. .ipynb 文件格式详解

.ipynb 是一个 JSON 格式的文本文件，其结构定义了一个 Notebook 的完整内容：单元格顺序、代码、输出、元数据等。理解这个结构有助于版本控制、程序化生成、以及故障排查。

2.1 基本结构

一个典型的 .ipynb 文件如下所示（缩略）：

json

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": "Hello, World!"
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": ["print('Hello, World!')"]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": ["# 这是一个标题"]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}

2.2 关键字段解析

  • nbformat 和 nbformat_minor：Notebook 格式版本，当前主流为 v4。

  • cells：数组，包含所有单元格。

  • metadata：Notebook 级元数据，包括内核信息、语言信息、扩展配置等。

  • cell_type：单元格类型，常见为 code、markdown、raw。

  • source：单元格源码（字符串列表或单个字符串）。

  • outputs：代码单元格的输出结果，可以是文本、图像、HTML、错误信息等。

  • execution_count：代码单元格的执行序号（若未执行则为 null）。

2.3 输出格式的多样性

outputs 中的 data 字段支持多种 MIME 类型，例如：

  • text/plain：纯文本

  • text/html：HTML 渲染

  • image/png：Base64 编码的图片

  • application/javascript：可执行的 JavaScript

  • text/latex：LaTeX 公式

这使得 Notebook 能够展示丰富的内容，甚至嵌入交互式控件。

2.4 与旧版本的区别

Jupyter Notebook 继承自 IPython Notebook（v3 及以下）。v4 之后，JSON 结构更清晰，支持多语言内核。现在几乎所有的工具都支持 v4。

3. 环境搭建与基本操作

3.1 安装方式

使用 pip 安装

bash

pip install notebook
jupyter notebook
使用 Anaconda 安装（推荐）

Anaconda 预装了 Jupyter Notebook 以及数百个数据科学库：

bash

conda install jupyter
使用 Docker

bash

docker run -p 8888:8888 jupyter/base-notebook

3.2 启动与界面

运行 jupyter notebook 后，浏览器自动打开 http://localhost:8888/tree，显示当前目录下的文件列表。可以新建 Notebook、文件夹，或上传已有文件。

3.3 界面组件

  • 菜单栏：文件、编辑、视图、插入、单元格、内核、帮助等。

  • 工具栏：保存、添加单元格、剪切/复制/粘贴、运行、停止、单元格类型切换等。

  • 单元格：核心工作区，可以编写代码或 Markdown。

  • 内核状态指示器：右上角显示内核状态（空闲/忙碌）。

  • 文件名称：默认 Untitled.ipynb，可点击修改。

3.4 基本操作快捷键

快捷键 功能
Shift+Enter 运行当前单元格，并选中下一个
Ctrl+Enter 运行当前单元格
Alt+Enter 运行当前单元格，并在下方插入新单元格
A 在上方插入单元格（命令模式）
B 在下方插入单元格
DD 删除当前单元格
M 转为 Markdown 单元格
Y 转为 Code 单元格
1~6 设为 Markdown 标题级别
Ctrl+S 保存
Esc 进入命令模式
Enter 进入编辑模式

3.5 命令模式 vs 编辑模式

  • 命令模式：蓝色边框，按键执行操作（如 A、B、DD）。

  • 编辑模式：绿色边框，可输入文本/代码。

4. 单元格类型与 Markdown 魔法

4.1 三种单元格类型

  • Code：执行代码，显示输出。

  • Markdown：渲染为富文本，支持标题、列表、图片、链接、LaTeX 公式等。

  • Raw NBConvert：不被 Jupyter 渲染，用于导出时保留原始文本。

4.2 Markdown 基础语法

markdown

# 一级标题
## 二级标题
### 三级标题

**粗体** *斜体*

- 无序列表
1. 有序列表

[链接文本](https://example.com)
![图片alt](image.png)

行内代码 `print()` 

代码块：
```python
print("Hello")

数学公式：$E = mc^2$ 或

∫0∞e−x2dx=π2∫0∞​e−x2dx=2π​​

text

### 4.3 Markdown 高级技巧

- **表格**：
  ```markdown
  | 列1 | 列2 |
  |-----|-----|
  | A   | B   |

  • 脚注：[^1] 和 [^1]: 脚注内容

  • HTML 支持：可以直接嵌入 HTML，例如 <font color="red">红色文字</font>，<details><summary>折叠内容</summary>...</details>。

  • 图像调整大小：使用 HTML <img src="image.png" width="300">。

  • 嵌入 YouTube 视频：

    html

    <iframe width="560" height="315" src="https://www.youtube.com/embed/..." frameborder="0" allowfullscreen></iframe>

4.4 在 Markdown 中引用单元格输出

通过 %%capture 魔法或 IPython.display 可以捕获输出并在 Markdown 中引用，但更常见的是直接在 Markdown 中嵌入变量值（需配合扩展如 ipython-sql 或自定义模板）。

5. 内核与交互式计算

5.1 内核概念

内核是一个独立进程，负责执行代码并返回输出。Jupyter 采用客户端-服务器模型：浏览器作为客户端，内核在后台运行。你可以中断、重启、或切换内核。

5.2 管理内核

  • 中断内核：当代码陷入死循环时，点击工具栏的 ⬛ 方块。

  • 重启内核：清空所有变量，从头开始执行。

  • 切换内核：通过 Kernel → Change kernel 选择其他语言内核。

5.3 多语言内核

Jupyter 支持超过 100 种语言，通过安装相应内核实现。常用内核：

  • IRkernel：R 语言

  • IJulia：Julia 语言

  • bash_kernel：Shell 命令

  • sparkmagic：连接 Spark 集群

  • SQL 内核：直接在单元格中执行 SQL 查询（如 ipython-sql 扩展）

安装示例：

bash

# R 内核
conda install -c r r-irkernel
# Julia 内核
julia -e 'using Pkg; Pkg.add("IJulia")'

5.4 变量共享与隔离

同一内核的所有单元格共享变量。重启内核会重置所有状态。注意不要误用同名变量覆盖。

5.5 异步与并发

在 Python 内核中，可以使用 asyncio 或 multiprocessing，但要注意 Jupyter 的 asyncio 事件循环可能冲突（需要 nest_asyncio 补丁）。

6. 高级功能：魔法命令、扩展与 Widgets

6.1 魔法命令（Magic Commands）

IPython 内核提供了丰富的魔法命令，分为行魔法（以 % 开头）和单元格魔法（以 %% 开头）。

常用行魔法

  • %time：单次运行时间

  • %timeit：多次运行取平均时间

  • %pwd：当前工作目录

  • %ls：列出目录文件

  • %matplotlib inline：内嵌 matplotlib 图表

  • %load：从文件加载代码到单元格

  • %run：执行 Python 脚本

  • %debug：进入调试器

常用单元格魔法

  • %%time：整个单元格的执行时间

  • %%timeit：整个单元格的多次计时

  • %%writefile：将单元格内容写入文件

  • %%capture：捕获单元格所有输出

  • %%bash：在 bash 中执行命令

  • %%javascript：执行 JavaScript 代码（前端渲染）

  • %%html：渲染 HTML

  • %%latex：渲染 LaTeX

示例：

python

%%time
import time
time.sleep(2)  # 显示执行时间

python

%%writefile my_script.py
print("Hello from file")

6.2 扩展（Extensions）

Jupyter Notebook 可以通过扩展增强功能。常用的扩展管理器是 jupyter_contrib_nbextensions。

安装：

bash

pip install jupyter_contrib_nbextensions
jupyter contrib nbextension install --user

打开 Notebook 后，顶部出现 Nbextensions 选项卡，可启用/配置扩展。

推荐扩展

  • Table of Contents (2)：自动生成目录，支持导航。

  • Hinterland：代码自动补全（实时弹窗）。

  • ExecuteTime：显示每个单元格的执行时间。

  • Variable Inspector：显示当前所有变量。

  • Collapsible Headings：折叠标题下的内容。

  • Code prettify：格式化代码。

  • Spellchecker：Markdown 拼写检查。

  • Autopep8：自动格式化 Python 代码。

6.3 交互式控件（ipywidgets）

ipywidgets 可以将 Notebook 变成交互式仪表盘。用户可以拖动滑块、输入文本、选择下拉菜单，动态更新图表。

安装：

bash

pip install ipywidgets
jupyter nbextension enable --py widgetsnbextension

示例：

python

import ipywidgets as widgets
from IPython.display import display

slider = widgets.IntSlider(value=5, min=0, max=10)
display(slider)

def on_change(change):
    print(f"当前值：{change['new']}")

slider.observe(on_change, names='value')

更复杂的交互可以用 interact：

python

from ipywidgets import interact

def f(x):
    return x**2

interact(f, x=10)

ipywidgets 还支持布局、选项卡、输出控件等，可构建完整应用。

6.4 其他高级输出

  • IPython.display：可以显示多种媒体，例如：

python

from IPython.display import display, Image, Audio, Video, HTML

display(Image(url='https://example.com/image.png'))
display(Audio(data=audio_array, rate=44100))
display(Video('video.mp4'))
display(HTML('<h1>Hello</h1>'))

  • matplotlib 动画：可以通过 display 更新动态图表。

7. 数据科学与可视化集成

7.1 与 pandas 的无缝协作

pandas 是数据科学核心库，其 DataFrame 在 Notebook 中会自动渲染为带滚动条的 HTML 表格，非常美观。

python

import pandas as pd
df = pd.read_csv('data.csv')
df.head()

此外，df.plot() 可以直接调用 matplotlib 绘图，图表内嵌。

7.2 可视化库的交互性

  • Matplotlib：默认静态图，配合 %matplotlib inline 或 %matplotlib notebook（可缩放/交互）。

  • Seaborn：基于 Matplotlib 的统计绘图，同样支持内嵌。

  • Plotly：生成交互式图表，可缩放、悬停显示数据。

    python

    import plotly.express as px
fig = px.scatter(df, x='x', y='y', color='category')
fig.show()

  • Bokeh：同样提供交互式图表，可通过 output_notebook() 渲染。

  • Altair：声明式可视化库，输出 Vega-Lite 规范，交互性强。

7.3 大数据集成

  • Dask：支持分布式计算，可与 Notebook 集成，提供与 pandas 类似的 API，但处理大于内存的数据。

  • Spark：通过 pyspark 内核或 sparkmagic 扩展，可以在 Notebook 中提交 Spark 作业。

7.4 机器学习框架

  • scikit-learn：模型训练、评估、可视化。

  • TensorFlow / PyTorch：可以逐步构建网络，观察损失曲线，甚至使用 TensorBoard 内嵌（通过 %tensorboard 魔法）。

7.5 数据库连接

  • SQLAlchemy：连接关系型数据库，将查询结果直接读入 DataFrame。

  • ipython-sql：在单元格中直接执行 SQL，将结果转为 DataFrame。

    python

    %load_ext sql
%sql sqlite:///mydb.db
%%sql
SELECT * FROM table;

8. 协作与版本控制

8.1 Git 与 .ipynb 文件的问题

由于 .ipynb 是 JSON 文件，且包含输出和元数据，使用 Git 管理时会遇到冲突难解决、diff 难以阅读的问题。因此需要一些策略。

8.2 最佳实践

  • 清除输出：提交前清空所有输出（Kernel → Restart & Clear Output），或使用 nbstripout 工具自动清除。

    bash

    pip install nbstripout
nbstripout my_notebook.ipynb

  • 使用 jupyterlab-git 扩展：提供图形化 Git 界面，支持 diff。

  • 配置 Git 属性：在 .gitattributes 中指定 .ipynb 为二进制，或使用 git diff 驱动。

  • 使用 nbdime：专门用于 diff 和 merge Notebook 的工具。

    bash

    pip install nbdime
nbdiff notebook1.ipynb notebook2.ipynb

    也可以配置为 Git 的 diff/merge 工具。

8.3 协同编辑

  • Google Colab：类似 Notebook，支持实时协作（类似 Google Docs）。

  • JupyterLab 实时协作：JupyterLab 3.0+ 支持实时协作（需安装 jupyter-collaboration 扩展）。

  • VS Code Live Share：可共享 Notebook 进行协同编辑。

8.4 代码审查

  • 使用 ReviewNB（商业工具）专门用于 Notebook 的代码审查。

  • 将 Notebook 导出为 PDF 或 HTML 供非技术同事查看。

9. 性能优化与调试技巧

9.1 性能分析

  • 使用 %timeit 测量小片段性能。

  • 使用 %prun 进行函数级性能分析（基于 cProfile）。

    python

    %prun my_function()

  • 使用 %lprun（需 line_profiler）逐行分析。

  • 使用 %memit（需 memory_profiler）查看内存占用。

9.2 内存管理

  • 使用 %who 查看所有变量，%who_ls 列出变量名。

  • 使用 %reset 清除所有变量，%reset -f 强制。

  • 使用 del variable 删除变量，必要时调用 gc.collect()。

9.3 调试

  • %debug：在异常发生后运行，进入交互式调试器（pdb）。

  • pdb.set_trace()：在代码中插入断点。

  • ipdb：增强的调试器，支持语法高亮。

  • %pdb on：自动在异常时启动调试器。

  • 使用 JupyterLab Debugger（需安装 jupyterlab-debugger）提供图形化断点调试。

9.4 避免常见性能陷阱

  • 不要在循环中频繁调用 print，会严重拖慢速度。

  • 使用向量化操作（pandas、NumPy）代替 Python 循环。

  • 注意单元格顺序：避免重复计算昂贵的操作，可将结果缓存。

  • 使用 %%capture 抑制不需要的输出。

10. 与外部工具集成：VS Code、PyCharm、云平台

10.1 VS Code

VS Code 内置 Jupyter 支持，可以直接打开 .ipynb 文件，支持：

  • 交互式执行单元格

  • 变量查看器

  • 调试器

  • Git 集成

  • 与 Python 脚本混合编辑

优势：本地编辑器体验，可与 Python 文件一起管理，支持代码补全、重构等。

10.2 PyCharm

PyCharm Professional 版本支持 Jupyter Notebook，功能包括：

  • 单元格执行与结果内嵌

  • 变量查看

  • 科学模式（SciView）

  • 与调试器集成

10.3 云平台

  • Google Colab：免费 GPU/TPU，自动保存到 Google Drive，支持协作，内置了许多常用库。

  • Kaggle Notebooks：Kaggle 竞赛环境，免费 GPU，数据集丰富。

  • Azure Notebooks：微软的托管服务（已迁移到 Visual Studio Online）。

  • Deepnote：现代 Notebook 协作平台，支持实时协作、环境持久化。

  • Databricks：企业级数据科学平台，Notebook 支持多语言、协作、作业调度。

10.4 远程内核

可以在本地 Notebook 连接到远程服务器上的内核（通过 SSH 隧道），适合使用远程 GPU 资源。

11. 部署与分享：NBViewer、JupyterHub、Binder

11.1 静态分享

  • NBViewer：输入 GitHub 上的 .ipynb 链接即可渲染，适合快速分享。

  • GitHub：GitHub 本身可以渲染 .ipynb 文件（只读），但加载大文件可能较慢。

  • 导出为 HTML/PDF：通过 File → Download as → HTML/PDF 生成静态文档。

11.2 动态部署

  • Binder：将 GitHub 仓库转换为可交互的 Notebook 环境。只需在仓库中包含 requirements.txt 或 environment.yml，Binder 会自动构建环境并启动。

  • JupyterHub：为团队/班级部署多用户 Jupyter 服务器，支持用户认证、资源隔离。

  • Voilà：将 Notebook 转换为独立的仪表盘应用，隐藏代码单元格，只显示输出和控件。

    bash

    pip install voila
voila my_notebook.ipynb

  • Papermill：参数化执行 Notebook，可用于生成报告或批量运行。

    bash

    papermill input.ipynb output.ipynb -p param1 value1

11.3 嵌入到网站

可以使用 nbconvert 将 Notebook 转换为 HTML 片段，嵌入到现有网站。

bash

jupyter nbconvert --to html --template basic my_notebook.ipynb

12. 常见问题与解决方案

12.1 内核死亡（Kernel Restarting）

可能原因：

  • 内存不足

  • 死循环或无限递归

  • C 扩展崩溃

解决：

  • 检查内存占用，重启内核，逐步执行定位问题。

  • 使用 %reset 清除变量。

12.2 大输出导致浏览器卡顿

  • 避免打印海量数据，使用 df.head() 代替 df。

  • 使用 %%capture 捕获不需要的输出。

  • 设置 pd.set_option('display.max_rows', 100) 限制显示行数。

12.3 路径问题

Notebook 的当前工作目录是启动 Jupyter 的目录，而不是 Notebook 所在目录。要获取 Notebook 所在目录，可以使用：

python

import os
notebook_dir = os.path.dirname(os.path.abspath('__file__'))  # 注意：__file__ 在 Notebook 中不可用
# 正确方法：
import os
print(os.getcwd())
# 或者使用 IPython 魔法：
%pwd

12.4 依赖管理

为保持可复现性，建议使用 requirements.txt 或 environment.yml 列出依赖。在 Binder 或 Colab 中，可通过 !pip install 安装，但最好在文档中说明。

12.5 代码补全失效

  • 检查是否启用了 Hinterland 扩展。

  • 尝试 Tab 键手动触发补全。

  • 重启内核或刷新页面。

12.6 无法导入自定义模块

确保自定义模块在 Python 路径中，可以在 Notebook 开头添加：

python

import sys
sys.path.append('/path/to/module')

13. 未来展望与替代工具

13.1 JupyterLab

JupyterLab 是下一代 Notebook 界面，采用多标签、可拖拽的面板，支持更多文件类型（文本、图像、CSV、终端等），且扩展性更强。Jupyter Notebook 的经典界面仍会维护，但新功能主要在 JupyterLab 中开发。

13.2 JupyterLite

JupyterLite 是直接在浏览器中运行的 Jupyter 环境（基于 WebAssembly），无需后端服务器，非常适合教学或静态网站托管。

13.3 替代工具

  • R Markdown：R 生态中的类似工具，可执行 R、Python、SQL 代码，生成 HTML/PDF/Word 报告。

  • Quarto：新一代可执行文档系统，支持多种语言（R、Python、Julia、Observable），输出格式丰富。

  • Observable：基于 JavaScript 的可视化 Notebook，专注交互式数据叙事。

  • Deepnote：云优先的协作 Notebook，UI 现代化，支持环境快照、集成数据库等。

13.4 与 AI 结合

  • GitHub Copilot 在 JupyterLab 和 VS Code 中提供 AI 代码补全。

  • Jupyter AI（官方扩展）：提供生成式 AI 助手，可以用自然语言生成代码、解释代码、修复错误。

  • 未来 Notebook 将更深度集成 AI，帮助自动生成数据分析流程。

# jupyter # ide # python
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

蒙特卡洛风光场景并通过削减法聚类法得到几个典型场景（包含Matlab代码和Python代码实现）

蒙特卡洛方法是一种基于随机抽样的数值计算方法，通过多次随机抽样来估计系统的行为，从而得到系统的统计性质。在风光模型中，蒙特卡洛方法可以用来模拟风速、风向和太阳光照的变化，进而评估风力和太阳能系统在不同条件下的性能。

avatar AtomGit开源社区

蒙特卡洛风光场景并通过削减法聚类法得到几个典型场景（包含Matlab代码和Python代码实现）

蒙特卡洛方法是一种基于随机抽样的数值计算方法，通过多次随机抽样来估计系统的行为，从而得到系统的统计性质。在风光模型中，蒙特卡洛方法可以用来模拟风速、风向和太阳光照的变化，进而评估风力和太阳能系统在不同条件下的性能。

avatar AtomGit开源社区

【EI复现】基于元模型优化算法的主从博弈多虚拟电厂动态定价和能量管理(Matlab代码实现）

基于元模型的优化算法是一种基于历史数据来驱动样本点的加入从而逼近局部或全局最优解的优化机制，能够改善传统启发式智能算法需要繁复数值模拟的缺陷，目前在飞行器设计等航空航天领域的应用[20]最为广泛，在电力系统方面也有初步的应用。提出基于 Kriging 元模型的博弈均衡算法，在求解过程中建立 Kriging 元模型替代 VPP 内部的能量管理模型，利用粒子群优化算法搜索优异采样点，更新修正 Krig

avatar AtomGit开源社区