如果你刚接触 Python 数据分析或者机器学习第一次听别人说“在 Jupyter 里跑一下”“把这个 .ipynb 发给我”的时候大概率会有点懵Jupyter 到底是个软件还是网站.ipynb 又是什么格式为什么做数据的人天天都在用这篇文章就直接把这两件事讲清楚Jupyter 环境怎么装、怎么启动、能不能用 GPU、怎么批量跑任务以及 .ipynb 文件的结构、打开方式、转换方式和常见坑。全文不绕弯子先给结论Jupyter 是一个让你在浏览器里写 Python 代码、立刻看到运行结果、还能把文字和图表混排在一起的交互式开发环境.ipynb 就是它的默认文件格式可以简单理解成“带代码和结果的富文本文档”。下面从安装、启动、使用、批量任务到排查一步步说完整。1. 核心能力速览能力项说明项目名称Jupyter Notebook / JupyterLab.ipynb 文件格式项目类型交互式笔记本开发环境支持 Python、R、Julia 等多种内核主要功能代码编写与即时运行、Markdown 笔记、数据可视化内嵌、公式渲染、幻灯片导出安装方式pip 或 conda 安装支持虚拟环境隔离启动方式命令行输入 jupyter notebook 或 jupyter lab浏览器自动打开支持平台Windows、Linux、macOS以及远程服务器硬件门槛纯文本和表格处理不需要 GPU训练深度学习模型时需要 NVIDIA 显卡和 CUDA接口能力提供 REST API可用 Python/curl 创建、执行、管理笔记本批量任务可通过 nbconvert、papermill 或其他调度工具批量执行适合场景数据分析、算法原型、教学演示、技术博客、机器学习实验记录不适合场景大型工程代码组织、高并发服务部署、纯脚本定时任务有更合适的工具从材料看Jupyter 最大的优势不是“能跑代码”而是把代码、运行结果、图表和说明文字放在同一个文件里。这正好满足数据分析和算法研究里“写一段、跑一段、看一段”的工作习惯。2. 适用场景与使用边界先看适合谁。数据科学入门者会用它做数据清洗和统计可视化算法工程师会用它迭代模型、观察 loss 曲线学生和老师会用它写实验报告、交作业技术博主也会用它生成带图和代码的教程。对这个群体来说Jupyter 的价值在于降低了反馈成本每写一行代码都能立刻看到结果不需要写完整脚本再运行也不用额外打开绘图窗口。但使用边界要分清楚。Jupyter 不是万能的代码编辑器不适合组织大型工程比如几十个模块的 Web 服务也不适合做定时生产任务因为它的设计目标是交互式探索不是持续运行更不适合直接当作生产接口服务虽然可以通过 API 控制但要上生产环境还是应该把逻辑抽取成正式服务。如果需要把笔记中的代码变成自动化流程通常要用 nbconvert 或 papermill 做批处理或者在开发完成后重写为 .py 脚本。合规方面也值得注意Jupyter 里可以读取本地文件、访问数据库、调用模型处理他人数据时要注意授权和隐私保护如果涉及人脸、声音、版权素材必须确保已获得合法授权在笔记本里保存数据库连接串、API Key、密钥等敏感信息非常危险因为 .ipynb 会原样保存输出内容一旦分享就会被看到。3. 环境准备与前置条件Jupyter 本身不挑机器最低配置只要有一台能装 Python 的电脑就行。但如果你要用它做深度学习或大数据分析机器配置会直接影响体验。下面按两种场景分别说明。3.1 基础环境操作系统Windows 10/11、Ubuntu 20.04、CentOS 7、macOS 都能安装。Python 版本建议 3.8 及以上新版 Jupyter 对 Python 3.9、3.10、3.11 都兼容良好。包管理工具pip 或 conda。建议用 conda 创建独立环境避免包冲突。浏览器Chrome、Edge、Firefox 都可以Jupyter 走本地 Web 服务用浏览器访问。端口占用Jupyter 默认使用 8888 端口如果冲突会自动往 8889、8890 递增也可以手动指定。关于 Jupyter 和“Juputer”这个拼写新手搜索时很容易把 Jupyter 拼成 Juputer这里主动说明一下Jupyter 的正确拼写是 J-u-p-y-t-e-r它是 Julia、Python、R 三个语言名称的组合但实际已经发展成支持 100 多种内核的通用交互式环境。如果你搜索 Juputer 发现找不到请直接使用 Jupyter 关键词。3.2 GPU 与 CUDA 环境可选如果要在 Jupyter 里跑 PyTorch 或 TensorFlow 训练需要满足NVIDIA 显卡比如 GTX 30 系、40 系或 50 系。安装与显卡匹配的 NVIDIA 驱动。安装对应版本的 CUDA Toolkit 和 cuDNN。在 Python 虚拟环境中安装 GPU 版 PyTorch。不同显卡、驱动和 CUDA 版本的兼容组合差异很大最稳妥的做法是去 PyTorch 官网选择与当前环境匹配的安装命令。不要盲目安装最新版 CUDA驱动版本未必支持。4. 安装部署与启动方式4.1 通过 pip 安装先确保 Python 已安装然后在终端或命令行中执行pip install jupyterlab notebook如果下载慢可以换国内镜像源pip install jupyterlab notebook -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后验证版本jupyter --version正常情况下会输出 jupyter_core、jupyter-notebook、jupyterlab 等组件的版本号。如果提示命令找不到说明 Python 的 Scripts 目录没有加入 PATH。4.2 通过 conda 安装如果你使用 Anaconda 或 Miniconda推荐创建独立环境再安装conda create -n jupyter_env python3.10 -y conda activate jupyter_env conda install jupyterlab notebook -c conda-forge -y这样做的优点是环境隔离换项目时不会污染全局 Python缺点是会额外占用几个 GB 磁盘空间。4.3 启动 Jupyter Notebook在命令行输入jupyter notebook启动成功后终端会输出一个本地地址通常是http://localhost:8888/tree浏览器会自动打开文件管理界面。如果没自动打开手动复制地址到浏览器访问即可。4.4 启动 JupyterLabJupyterLab 是 Jupyter 的下一代界面界面更像 IDE支持多标签页、文件拖拽、终端集成。启动命令jupyter lab访问地址同样默认是 8888 端口。注意notebook 和 lab 不能同时占用同一个端口如果出现端口冲突可以指定端口jupyter lab --port 88894.5 设置登录密码默认情况下第一次访问 notebook 或 lab 时会要求输入 token也就是启动命令里自动生成的一长串字母数字。如果你在服务器上部署不想每次都用 token可以设置固定密码jupyter server password执行后按提示输入两次密码即可。从安全性上考虑这个功能只建议在可信内网环境中使用如果服务暴露到公网务必要开启密码并限制监听地址。4.6 远程服务器访问在远程服务器上启动时为了安全不要监听所有地址而是通过 SSH 端口转发访问ssh -L 8888:127.0.0.1:8888 userremote_server_ip然后在服务器上正常启动 jupyter notebook 或 jupyter lab本地浏览器访问 http://localhost:8888 就能打开远程环境。这是很多团队共享服务器跑模型时的常用方式。4.7 Docker 启动可选如果你的团队统一使用 Docker可以用官方镜像快速拉起docker run -p 8888:8888 -v /local/project:/home/jovyan/work jupyter/datascience-notebook:latest这个命令会把当前机器的 /local/project 目录挂载到容器内的 /home/jovyan/work 目录容器里的代码和数据都在这份挂载中。需要注意镜像下载体积较大首次拉取可能要等一段时间。4.8 在 VS Code 中直接使用 ipynb除了浏览器VS Code 也原生支持 .ipynb 文件。安装 Python 扩展和 Jupyter 扩展后直接双击 .ipynb 文件就能打开笔记本界面选择内核后即可运行单元格。它和浏览器版 Jupyter 共享相同的内核协议但编辑体验更接近代码编辑器适合已经习惯 VS Code 的人。5. .ipynb 文件结构解析.ipynb 文件本质上是一个 JSON 文件。用文本编辑器打开后可以看到顶层有cells、metadata、nbformat、nbformat_minor等字段。cells是核心它是一个列表每个单元格就是一个字典根据 cell_type 可以分为 code 类型、markdown 类型和 raw 类型。code 类型的单元格结构大致是{ cell_type: code, execution_count: 1, metadata: {}, outputs: [], source: [ print(hello jupyter) ] }execution_count单元格的执行计数。source单元格源码注意它以字符串数组形式存储每行是一个元素。outputs代码运行后的输出结果包括文本、图片、富文本等。metadata单元格元数据通常用于显示设置。markdown 类型的单元格把cell_type改成 markdownsource 中写 Markdown 文本渲染后会显示为排版好的文字、标题、列表、链接和图片。raw 单元格不做渲染只当做纯文本保存。这里有一个容易踩的坑.ipynb 文件是 JSON默认情况下 Git 合并会把大量单元格位置变化视为冲突导致代码 review 很痛苦。常见的缓解办法是使用 jupytext 把笔记本维护成 .py 或 .md 文本格式再用工具在需要时转换为 .ipynb或者在 Git 里使用 nbdime 做专门的笔记本差异比较工具。另一个坑是 .ipynb 会把代码运行结果原样保存。如果某个单元格输出了一张几 MB 的图片或者打印了很长的 DataFrame文件体积会迅速膨胀提交到 Git 仓库后会让仓库越来越大。处理办法是在导出或提交前清理输出可以用jupyter nbconvert --ClearOutputPreprocessor.enabledTrue --inplace notebook.ipynb清空输出或者使用 VS Code/Notebook 界面里的 “清理输出”按钮。6. 功能测试与效果验证环境装完、文件结构也了解了下面直接动手验证 Jupyter 是否可用。6.1 创建并运行第一个代码单元格在 JupyterLab 界面中点击左上角“”新建启动器选择 Python 3 内核创建一个新笔记本。在第一个单元格里输入print(hello jupyter) 1 1按 ShiftEnter 运行。预期结果是输出 hello jupyter并在下方显示2。判断成功的标准是单元格左侧出现执行计数 [1]说明内核已连接并执行成功。如果按 ShiftEnter 没有反应重点检查内核是否连接成功。界面上如果显示 “No kernel” 或连接超时问题通常出在 Python 环境不对或 jupyter-client 版本冲突。6.2 Markdown 和代码混排测试新建一个单元格把类型切换为 Markdown输入# 测试标题 这是 **加粗文字**。 - 项目 A - 项目 B按 ShiftEnter 渲染预期看到格式化后的标题、加粗文本和列表。这一步验证的是 notebook 的文档能力。实际写技术笔记时可以在一段 Markdown 说明之后紧跟着代码单元格和输出结果最终形成完整实验报告。6.3 数据可视化验证数据科学场景里最常用的验证方式是绘一张图。在代码单元格中输入import matplotlib.pyplot as plt import numpy as np x np.linspace(0, 10, 100) y np.sin(x) plt.plot(x, y) plt.title(sin(x) test) plt.show()运行后应该在单元格下方出现一张正弦曲线图。如果出现ModuleNotFoundError: No module named matplotlib就先执行pip install matplotlib然后重启内核再运行。重启内核的方法是菜单栏 Kernel - Restart Kernel。6.4 导出为 .py 和 .html验证笔记本能正常导出使用 nbconvert 命令jupyter nbconvert --to script notebook.ipynb该命令会生成 notebook.py里面只有代码单元格的内容Markdown 单元格会被转换为注释。这个功能适合在开发完成后把原型代码整理成正式脚本。导出 HTML 用于分享或报告jupyter nbconvert --to html notebook.ipynb生成的 HTML 文件可以直接用浏览器打开保留了代码、输出和 Markdown 渲染结果。7. 接口 API 与批量任务Jupyter 除了交互式操作之外还提供了一套 REST API可以用 HTTP 请求创建笔记本、执行代码、获取输出。这在做自动化测试、批量生成报告和统一调度场景下非常有用。7.1 启动 API 服务Jupyter Server 在启动时就自带 HTTP API不需要额外插件。默认情况下需要先拿到访问 token。启动时如果忘了 token可以在终端执行jupyter server list输出内容里会包含当前服务的 URL 和 token。例如http://localhost:8888/?tokenabc123def456后面的abc123def456就是访问 API 时需要使用的 token。7.2 创建会话并执行代码的 Python 示例下面用一个 Python 脚本演示通过 API 创建笔记本、执行代码并读取结果。这个示例重点在于理解请求流程实际使用时需要根据你的 Jupyter 版本调整细节。import requests import json import uuid base_url http://127.0.0.1:8888 token 你的token headers { Authorization: ftoken {token}, Content-Type: application/json } # 1. 创建一条内容为 print(api test) 的代码执行请求 payload { cell: print(api test), kernel_name: python3 } # 2. 初始化一个会话 session_id str(uuid.uuid4()) kernel_resp requests.post( f{base_url}/api/kernels, headersheaders, json{name: python3}, timeout30 ) if kernel_resp.status_code 201: kernel_id kernel_resp.json()[id] print(kernel started:, kernel_id) # 3. 向内核发送执行请求 exec_payload { code: print(api test), silent: False, store_history: True, user_expressions: {}, allow_stdin: False, stop_on_error: True } exec_resp requests.post( f{base_url}/api/kernels/{kernel_id}/execute, headersheaders, jsonexec_payload, timeout60 ) print(execute status:, exec_resp.status_code) # 4. 清理内核避免资源占用 requests.delete(f{base_url}/api/kernels/{kernel_id}, headersheaders, timeout30) else: print(kernel start failed, kernel_resp.status_code, kernel_resp.text)这个脚本演示了一条最基础的链路创建内核、执行代码、删除内核。实际生产中不建议频繁创建和删除内核更优方案是复用已经启动的内核或在批处理层面用 papermill。7.3 批量转换 .ipynb 为 .py工作中经常遇到几十个 notebook 需要统一转成脚本或 HTML。nbconvert 本身支持目录和通配符jupyter nbconvert --to script output_dir/*.ipynb jupyter nbconvert --to html output_dir/*.ipynb也可以写一个简单脚本批量处理import subprocess from pathlib import Path notebooks list(Path(./notebooks).glob(*.ipynb)) for nb in notebooks: result subprocess.run( [jupyter, nbconvert, --to, script, str(nb)], capture_outputTrue, textTrue ) print(nb.name, result.returncode)这样就能把某个目录下的所有 .ipynb 文件批量转换为 .py 文件适合交付代码或做代码审计时使用。注意批量转换前建议先在一个小目录里测试确认导出内容和预期一致避免大批量执行后才发现格式问题。7.4 参数化批处理示例papermill如果每个 notebook 需要跑不同参数比如分别处理不同月份的销售数据可以在笔记本的某个单元格中标记带参数变量然后用 papermill 执行。安装pip install papermill假设 notebook 中第一个代码单元格是month 2025-01 print(month)执行参数化运行papermill input.ipynb output_2025_01.ipynb -p month 2025-01papermill 会把month的值注入笔记本参数单元格依次运行所有单元格并把结果保存为新的 output 文件。输出文件名建议带上参数名方便后续归档。7.5 批处理时的失败重试建议批量任务跑了几十个 notebook最怕中途某个单元格报错导致后续任务全挂。建议给每个任务写独立输出文件这样单个失败不影响其他任务的结果。在循环脚本中加入 try/except记录失败列表。为每个 notebook 设置合理的超时时间。定期清理长时间未使用但仍在运行的 kernel避免内存被大量吃掉。如果数据量很大考虑按批分片执行单次只处理一个文件。8. 资源占用与性能观察8.1 内存观察方式启动 Jupyter 后系统里会出现 jupyter-server、jupyter-lab 等进程以及按内核数量区分的 ipykernel 进程。每个代码单元格执行时内存使用主要体现在对应内核进程中。在 Linux/Mac 上查看ps aux | grep ipykernel在 Windows 上可以用任务管理器中按 CPU 和内存排序找到 python.exe 或 python3.exe 进程。一个长期运行的 notebook 如果反复执行大数据操作内核内存会持续增长这是正常现象但如果内存持续不释放考虑重启内核。8.2 显存观察方式GPU 场景当你在 Jupyter 中运行 PyTorch 时可以用 nvidia-smi 观察显存占用。在终端执行nvidia-smi每次训练模型时显存变化主要取决于 batch size、模型大小、输入分辨率。如果显存不够常见手段是降低 batch size、降低图像分辨率、使用混合精度训练或使用梯度累积。如果模型仍然无法加载很可能是模型参数规模超过了显卡容量需要更换更大的显卡或使用 CPU 推理。8.3 大输出对笔记本性能的影响notebook 中如果直接打印上万行 DataFrame浏览器会卡顿文件体积也会增大。优化建议打印数据前先用df.head(10)或df.sample(5)查看前几行。图片输出用plt.savefig()保存到文件不要全部内嵌在笔记本里。及时清理不重要的输出单元格右键选择 “Clear Cell Output”。使用 JupyterLab 的 “Run All” 批量运行前先确认是否所有单元格都要执行避免长时间卡住。8.4 降低内存和磁盘占用的方法使用虚拟环境不要把所有包装到全局环境避免包版本冲突导致反复重装。notebook 中不要保存大对象比如几百 MB 的 DataFrame 序列化结果。定期清理旧的 .ipynb 输出文件避免目录无限膨胀。在 Git 仓库中配置*.ipynb输出清理脚本或者用 nbdime 减少冲突和体积。9. 常见问题与排查方法问题现象可能原因排查方式解决方案启动时提示 jupyter 不是内部命令Python Scripts 目录未加入 PATH执行 where python 查看路径并检查环境变量把 Scripts 目录添加到 PATH或使用 python -m jupyter notebook 启动浏览器打开后显示无内核Python 环境或 ipykernel 未安装查看终端启动日志执行 pip install ipykernel然后重启 Jupyter内核一直显示正在连接端口占用或内核崩溃检查终端日志和端口占用换端口启动或重启内核单元格运行后没有输出代码逻辑没打印结果检查单元格源码使用 print() 输出或检查是否把输出误存到变量提示 ModuleNotFoundError当前环境的包缺失在 notebook 中执行 !pip list 查看已装包执行 pip install 对应包8888 端口被占用之前有 jupyter 进程未关闭lsof -i:8888 或 netstat -ano杀掉旧进程或使用 --port 8889笔记本文件打不开文件损坏或 JSON 格式错误用文本编辑器打开看根字段从版本控制恢复或尝试 jq 检查 JSON 语法JupyterLab 访问很慢浏览器缓存问题或扩展过多清理浏览器缓存禁用不用的扩展使用无痕模式验证或重置扩展设置模型训练时显存不足batch 太大或模型太大nvidia-smi 查看显存占用降低 batch size、分辨率或启用混合精度API 调用返回 403token 错误或未带 Authorization 头检查 token 是否过期重新运行 jupyter server list 获取最新 tokenGit 合并 ipynb 冲突严重JSON 结构导致 diff 不友好使用 nbdime 或 jupytext将 ipynb 转成纯文本格式维护10. 最佳实践与使用建议第一建立一个规范的目录结构。建议把 notebook、数据、输出、代码模块分开目录管理项目根目录/ ├── notebooks/ # 存放 .ipynb ├── data/ # 存放原始数据和中间结果 ├── outputs/ # 存放图表、转换后的文件 ├── src/ # 存放通用函数和正式代码模块 └── requirements.txt这样在多个 notebook 之间复用代码时可以把通用函数都放到 src 目录用 import 引用避免每个 notebook 都复制一遍函数定义。第二第一次运行新环境时先用最小的数据集跑通全流程再换真实数据。比如先用 10 条样本验证代码逻辑确认输出格式正确后再加载完整数据。这能显著减少排错时间。第三把 Jupyter 当作实验记录工具而不是生产代码仓库。真正稳定运行的定时任务、Web 服务、批处理脚本应抽取为 .py 文件并纳入正式工程管理。Jupyter 的核心价值是快速验证和可视化不是替代工程体系。第四注意合规。使用他人的图像、音频、文本、代码时确认授权处理包含个人信息的数据时脱敏后使用不要把数据库密码、API Key 直接写在 notebook 中并上传公开仓库。模型训练涉及人脸、声音等敏感信息时必须确保有合法授权。第五定期清理和归档。notebook 的中间版本如果不再需要及时删掉或归档重要节点使用 Git 打标签。运行大批量任务前先在小范围试跑确认参数正确再全量执行。第六善用扩展和生态。JupyterLab 支持插件扩展可以安装代码格式化、目录大纲、Git 集成等功能让编辑体验更接近专业 IDE。但插件不宜装太多装得越多启动越慢。11. 总结与下一步Jupyter 最值得尝试的地方是它的即时反馈写代码立刻看到结果配合 Markdown、图表、公式一次完成“记录、实现、展示”三个环节。.ipynb 作为这一体验的载体既是代码文件也是报告文件理解了它的 JSON 结构和常用操作你在数据分析路上会顺畅很多。最先要验证的功能是创建笔记本、运行一个 Python 代码单元格、画一张 matplotlib 图表、导出为 .py 文件。这四个步骤覆盖了 Jupyter 的基本闭环。最容易踩的坑是环境变量没有配好导致 jupyter 命令找不到、内核连接失败、显存不足时不知道去哪里看资源占用、以及 .ipynb 文件在团队协作时冲突不断。这些问题都可以通过前面章节的环境检查、资源观察和 git 辅助工具来解决。下一步可以继续探索的方向包括用 papermill 做参数化批处理、把 notebook 接入定时任务框架、使用 jupytext 把 notebook 纳入纯文本协作流程以及把稳定逻辑抽出成 API 服务。当你把交互式探索和工程化交付拆开之后Jupyter 的效率优势会进一步放大。