Jupyter Notebook 不是一个新的东西但它是 Python 数据分析绕不开的基础设施。很多新手的第一步是装 Python而数据分析的第一步通常是打开 Notebook写几段代码、看几个图表、再保存成带输出的文档。这篇文章要解决的就是三件事Jupyter Notebook 怎么装、怎么用、遇到报错怎么排。如果你关心 Python 数据分析、数据可视化、机器学习实验管理这篇文章可以直接收藏。Jupyter Notebook 是一个开源的 Web 交互式笔记本工具支持 Python、R、Julia 等多种内核。它最大的价值不是写代码而是把“代码、运行结果、图表、文字说明”全部放在同一个页面里。数据分析师可以把清洗过程、统计结果、可视化图、结论说明写在一个 notebook 文件里既方便自己复盘也方便发给同事看。相比直接在 PyCharm 或 VS Code 里写一个完整脚本Jupyter Notebook 更适合探索性分析和教学演示。本文会从环境准备开始带你完成安装、启动、编写第一个分析示例、画图验证、批量导出再到常见问题排查。整个过程不需要复杂的命令行知识但会给出可复制的命令和可对照的检查思路。你会看到 Notebook 和 Lab 的区别也会看到怎么和 PyCharm、VS Code 集成。不管你是刚接触 Python 的新手还是已经写了几年脚本的老手这篇文章都值得留一份备用。1. 核心能力速览能力项说明项目类型开源 Web 交互式笔记本工具开发方Jupyter 社区Project Jupyter主要功能交互式代码执行、数据清洗、数据可视化、文档演示、报告导出支持语言Python、R、Julia 等需安装对应内核安装方式pip 安装或 Anaconda 安装启动方式终端执行jupyter notebook或jupyter lab默认端口8888可自定义是否支持 API支持内核网关但这不是核心用途是否支持批量任务原生支持批量导出可通过脚本批量执行 notebook适合场景Python 数据分析、机器学习实验、数据可视化、教学演示这里要特别说明一点Jupyter Notebook 本身不限定显卡不用 GPU 也能跑。它只是一个交互式编程环境真正的算力取决于 Python 解释器和后端库。显卡配置主要影响的是你在 Notebook 里跑深度学习还是普通数据分析。如果你只是做 pandas 清洗和 matplotlib 画图普通 CPU 电脑完全够用。2. 适用场景与使用边界Jupyter Notebook 最适合下列几类场景数据分析探索读入 CSV、Excel、数据库数据做清洗、聚合、透视、画图。机器学习实验在 notebook 里加载数据集训练模型查看指标曲线。教学与演示按单元格逐步讲解代码学生可以边看边改边执行。技术文档把代码、输出、文字说明、图表打包成一个 .ipynb 文件比纯 Word 文档直观。快速原型验证先验证接口返回格式、验证算法逻辑再把代码整理成正式脚本。它不适合什么场景大型软件工程需要模块化组织、单元测试、依赖管理和长期维护的大型项目更适合 PyCharm 或 VS Code 配合标准 Python 工程结构。高频定时调度如果要做每天定时执行的数据管道更推荐纯 Python 脚本配合任务调度器而不是依赖手动打开 Notebook。大量代码版本管理.ipynb 文件本质是 JSON 格式多人协作时合并冲突比普通 .py 文件麻烦。这不是说不能用但需要团队约定好使用方式。使用边界方面还有一个容易被忽视的点notebook 文件里保存的不仅是代码还有输出结果包括图片、表格、日志。如果涉及敏感数据、客户信息、人脸照片、声音文件导出和分发前要检查输出是否包含不应外泄的内容。分享 notebook 之前建议先清空输出可以通过菜单或 nbconvert 工具实现再提交版本仓库。这也是数据隐私和版权的合规要求。3. 环境准备与前置条件安装 Jupyter Notebook 之前先确认三件事Python 环境、包管理工具、浏览器。3.1 确认 Python 和 pipJupyter Notebook 是基于 Python 的工具所以第一步是确认电脑上已经安装了 Python。打开终端Windows 使用 CMD 或 PowerShellmacOS 和 Linux 使用 Terminal输入python --version pip --version如果输出类似Python 3.x.x和pip 2x.x说明基础环境正常。如果提示python不是内部或外部命令常见原因是 Python 没有加入系统 PATH。解决方式有两种重新安装 Python在安装向导勾选“Add Python to PATH”。手动把 Python 的安装目录和 Scripts 目录加入系统环境变量。这里要说明不同 Python 发行版对 PATH 的处理方式不完全一样更稳妥的判断是以安装时的界面选项为准。如果你装了 Anaconda也可以直接用 Anaconda Prompt 进入环境。3.2 选择安装方式安装 Jupyter Notebook 常用方式有两种pip 安装和 Anaconda 安装。方式优点适用人群pip 安装轻量Python 环境已有的情况下只需一条命令已有 Python 环境只补装 NotebookAnaconda 安装自带 Python、Jupyter、pandas、numpy、matplotlib 等数百个库新手不想一个个装依赖或需要科学计算全家桶如果你只是为了数据分析不想折腾依赖关系可以直接装 Anaconda。但 Anaconda 体积较大安装时间也长。如果电脑上已经有 PyCharm 或 VS Code并且已经配置好 Python 环境那么 pip 安装更省事。注意两个方式不要混着用否则可能出现包路径混乱导致命令行能启动 Notebook但 IDE 里找不到内核。3.3 浏览器要求Jupyter Notebook 是 Web 界面默认会在浏览器打开。建议使用 Chrome 或 Edge遇到一些旧版本浏览器可能显示异常。如果打开后页面空白优先换浏览器测试。后面排查章节会提到这一步。4. 安装部署与启动方式4.1 使用 pip 安装 Jupyter Notebook在终端执行pip install jupyter notebook这里会同时安装 notebook、ipykernel 等相关依赖。安装完毕后验证版本jupyter notebook --version如果直接执行jupyter提示命令找不到可以尝试用以下方式代替python -m jupyter notebook --versionpython -m指定通过当前 Python 解释器执行模块可以用来排查命令是否在 PATH 中。如果你仍然拿到No module named jupyter说明当前 Python 环境里没有安装成功或者 pip 安装到了另一个环境。如果你想用新的 JupyterLab 界面再补装pip install jupyterlabJupyterLab 是下一代 Notebook 界面支持文件管理、终端、多标签页同一个地址下可以切换使用。4.2 使用 Anaconda 安装Anaconda 安装包内置了 Jupyter Notebook。安装完成后在开始菜单找到 Anaconda Prompt启动后执行jupyter notebookAnaconda 还允许创建独立的 conda 环境conda create -n myenv python3.11 conda activate myenv pip install jupyter notebook这种做法的好处是每个项目一个环境不会污染全局 Python。数据分析项目越来越多时环境隔离能帮你省掉大量依赖冲突时间。4.3 启动 Jupyter Notebook安装完成后在终端执行jupyter notebook启动后终端会输出一堆日志其中包含一个本地地址通常是http://localhost:8888/tree默认端口是 8888。如果端口被占用启动时会出现类似“address already in use”的报错。此时指定一个空闲端口jupyter notebook --port 8889如果你不希望启动时自动打开浏览器可以加--no-browserjupyter notebook --no-browser这种模式适合在服务器上运行然后通过浏览器手动访问地址。浏览器打开后你会看到文件列表页面这就是 Notebook 的管理界面。点击右上角“New”可以创建新的 Python 3 笔记本。4.4 自定义配置Jupyter 支持通过配置文件设置默认启动参数。生成配置文件的命令是jupyter notebook --generate-config生成的配置文件通常在~/.jupyter/jupyter_notebook_config.py。你可以修改默认端口、设置密码、指定 notebook 文件目录等。例如c.NotebookApp.ip 127.0.0.1 c.NotebookApp.port 8888 c.NotebookApp.open_browser False注意配置文件项很多没有把握不要大量修改只改动明确需要的项即可。修改后重启 Jupyter 生效。5. 功能测试与效果验证启动成功之后建议按下面几步走一遍确认每个基础功能都正常。这一步很重要先验证最小可用链路再进入实际分析任务排错效率会高很多。5.1 第一个单元格代码执行测试新建一个笔记本后默认单元格是代码模式。输入print(Hello, Jupyter)按下Shift Enter执行。如果下方输出Hello, Jupyter说明代码内核连接正常。如果左侧没有出现In [1]说明内核没有启动后面排查章节会处理。5.2 Markdown 单元格测试在第二个单元格中按M把单元格切换为 Markdown 模式输入# 数据分析演示 这是一个 **Markdown** 单元格可以写公式、列表和说明。按Shift Enter单元格会渲染成带格式的文字。Jupyter Notebook 的核心能力之一就是代码和文档混排这一步是验证该能力是否正常的快速方式。5.3 数据分析和可视化验证安装数据分析常用库pip install pandas numpy matplotlib回到笔记本写一个简单的数据生成和可视化示例import numpy as np import pandas as pd import matplotlib.pyplot as plt # 生成一份带随机波动的销售数据 dates pd.date_range(2024-01-01, periods30, freqD) sales np.random.normal(loc100, scale15, size30) df pd.DataFrame({日期: dates, 销售额: sales}) print(df.head())如果前面已经配置了让图表在页面内显示的魔法命令可以在代码前加上%matplotlib inline然后画图plt.plot(df[日期], df[销售额]) plt.title(每日销售额趋势) plt.xlabel(日期) plt.ylabel(销售额) plt.show()执行成功后会直接在 notebook 页面内显示图片。这是判断数据分析环境是否可用的关键一步。要注意如果系统缺少中文字体图中标题可能显示成方块这不是 Jupyter 的问题是 matplotlib 字体配置问题后面常见问题部分会讲。5.4 魔法命令测试Jupyter 内置魔法命令这是区别于普通 Python 脚本的重要功能。常用三个%time sum(range(1000000))这个命令会统计单次执行时间。%timeit sum(range(1000000))这个命令会多次执行并取平均值适合测试代码性能。%%time total 0 for i in range(1000000): total i print(total)%%time放在单元格顶部统计整个单元格的执行时间。通过这几个命令你可以快速评估数据量和循环逻辑的运行耗时进而判断是否需要优化。5.5 导出验证写好的 notebook 需要分享时用内置导出功能生成 HTML 或 Markdown 文件。菜单路径是File - Download as。也可以使用命令行工具批量导出jupyter nbconvert --to html notebook.ipynb这个命令会生成同名的 HTML 文件可以在浏览器直接打开。如果想导出 Python 脚本jupyter nbconvert --to script notebook.ipynb这个功能适合把探索完成的代码整理成正式脚本。6. JupyterLab 与 Notebook 怎么选如何与 IDE 集成很多人会纠结用经典 Notebook 界面还是 JupyterLab其实两者底层内核是一样的区别在交互界面。经典 Notebook 是文件列表页面 单个笔记本页面结构简单适合刚入门。JupyterLab 则把文件浏览器、编辑器、终端、笔记本集成到一个界面里更适合多任务并行。如果是简单演示经典 Notebook 足够了。如果经常同时打开多个 notebook 或需要查看 CSV 文件JupyterLab 更顺手。启动命令是jupyter labJupyterLab 与经典 Notebook 相比还有几个实际优势支持拖拽窗口布局、内置文件管理器、支持主题切换。另外它在浏览器里打开多个 .ipynb 文件时不容易出现标签页混乱的问题。和编辑器集成方面这里也补充说明。VS Code 安装 Python 扩展后可以直接打开 .ipynb 文件选中代码块运行右键还可以把代码块中的代码发送到交互式窗口。PyCharm 专业版也支持 Jupyter Notebook打开 .ipynb 后会在编辑器里渲染单元格运行结果社区版支持相对有限。如果你电脑上已经装了 PyCharm但不想在浏览器和 IDE 之间来回切换可以先用 IDE 打开 notebook 测试。要注意的是IDE 内置的 Notebook 渲染界面与官方 Web 界面不完全一致遇到某些扩展组件不显示时优先回到 Web 页面验证。7. 批量任务与自动化导出Jupyter Notebook 原生没有复杂的任务队列系统但可以通过命令方式批量处理多个 notebook 文件。常见做法是写一个循环脚本依次执行导出或执行任务。7.1 批量导出为 HTML 或 Markdown假设一个目录下有多个 .ipynb 文件for f in *.ipynb; do jupyter nbconvert --to markdown $f; done在 Windows PowerShell 中对应的语法是Get-ChildItem -Filter *.ipynb | ForEach-Object { jupyter nbconvert --to markdown $_.Name }这个命令会把每个 notebook 转成 Markdown 文档适合生成文档合集。7.2 自动执行 notebook 文件nbconvert 还有一个--execute参数可以在不打开浏览器的情况下运行整个 notebookjupyter nbconvert --to notebook --execute my_analysis.ipynb执行完成后会生成一个新的 .ipynb 文件里面已经包含最新的输出。你可以在文件名前面加前缀来区分jupyter nbconvert --to notebook --execute my_analysis.ipynb --output executed_my_analysis.ipynb--ExecutePreprocessor.timeout参数可以控制单个单元格超时时间jupyter nbconvert --to notebook --execute my_analysis.ipynb --ExecutePreprocessor.timeout120如果 notebook 中有耗时的训练代码这个参数需要调大默认 30 秒往往不够。7.3 使用参数化执行如果同一个 notebook 要针对不同数据集或不同参数反复运行可以考虑使用 Papermill 这样的第三方工具。Papermill 是 Jupyter 生态中常用的参数化执行工具它的思路是在 notebook 中标记一个参数单元格每次执行时传入新参数生成新的输出 notebook。安装方式pip install papermill执行示例papermill input.ipynb output.ipynb -p date 2024-06-01-p用来传入参数。这个方式适合做一批定时执行的报告比如每天生成一份销售日报。不过 Papermill 不是 Jupyter 默认组件是否使用要结合项目规模和团队维护能力来判断。如果只是偶尔处理三五个文件直接用 nbconvert 批量执行就够了。8. 资源占用与性能观察Jupyter Notebook 启动后浏览器页面本身内存占用不高真正占用内存的是 Python 内核。每一个打开的 notebook 对应一个 Python 内核进程数据量一旦变大内存会明显上涨。这里给出几个实用的观察和优化方法。8.1 查看内核状态在 Web 页面顶部菜单中点击Kernel - Restart可以重启内核。如果长时间执行了内存占用很大的任务重启内核可以释放内存但代价是已定义的变量全部清除。8.2 查看内存占用Windows 用户可以在任务管理器中找到对应 Python 进程查看内存占用。如果同时打开 5 个 notebook就有可能出现 5 个 Python 进程每个进程占用独立内存。这是正常现象但不适合长时间挂着不用的 notebook。不用的笔记本建议及时关闭。8.3 性能优化建议读取大数据文件时先只读需要的列而不是全表载入。在函数内部避免重复创建大对象。遍历 DataFrame 时尽量用 pandas 的向量化操作不要写 for 循环。长时间训练任务建议输出中间结果避免内核卡死。如果代码执行了很久没有输出先用%time定位耗时单元格再决定是否优化。内存占用需要以实际机器规格和数据量大小为准不同电脑表现差异很大。最稳妥的方法是观察任务管理器中的内存走势不要等到卡死再处理。9. 常见问题与排查方法问题现象可能原因排查方式解决方案jupyter命令找不到Python 没加入 PATH 或未安装成功执行python -m jupyter --version重新安装 Python 并勾选 Add to PATH或使用python -m方式启动启动后浏览器页面空白浏览器兼容问题或缓存冲突换 Chrome/Edge清浏览器缓存升级浏览器禁用问题插件重启 Jupyter 服务端口被占用8888 端口已被其他进程使用查看终端报错信息启动时加--port 8889内核一直显示 Connecting内核启动失败或 ipykernel 缺失查看终端日志重新安装ipykernel或重启内核图表中文显示方块matplotlib 缺少中文字体运行print(matplotlib.get_cachedir())检查字体安装中文字体并设置 rcParams 字体单元格执行卡住代码死循环或资源耗尽观察内核状态点击菜单栏重启内核终止任务优化代码后重试保存的 notebook 打不开文件损坏或 JSON 格式错误用文件编辑器打开检查使用备份恢复或从 checkpoints 中恢复之前能打开现在打不开内核或 Python 环境被改动查看终端日志检查最近安装包在独立 conda 环境重装 Jupyter这里补充说明几个高频问题的细节。第一个细节jupyter命令找不到在 Windows 上很常见。如果已经通过pip install安装了但 CMD 依然找不到可以先用python -m jupyter notebook启动。这种方式的启动效果是一样的只是不需要依赖 PATH。第二个细节打开后空白。旧版浏览器或者安全设置过严可能导致页面加载不出来。先换个浏览器测试如果还有问题打开浏览器开发者工具查看 Console 报错通常能快速定位是网络问题还是渲染问题。第三个细节内核连不上。最常见的原因是当前 Python 环境缺少 ipykernel。执行pip install ipykernel后在 Notebook 页面点击Kernel - Restart再试。如果仍然连不上新建一个简单 notebook只执行一条print(1)确认问题是否与之前的代码有关。第四个细节绘图中文乱码。这是初学者经常遇到但不是 Jupyter 本身的问题。解决方案是在代码开头设置中文字体import matplotlib import matplotlib.pyplot as plt plt.rcParams[font.sans-serif] [SimHei, Microsoft YaHei] plt.rcParams[axes.unicode_minus] False不同操作系统中文字体名称不同Windows 常用SimHei和Microsoft YaHeimacOS 常用PingFang SC。如果字体名称不存在matplotlib 会保持默认字体。10. 最佳实践与使用建议10.1 目录划分建议把项目目录按功能划分notebooks/ ├── data/ ├── notebooks/ │ ├── 01_数据清洗.ipynb │ └── 02_可视化分析.ipynb ├── outputs/ │ └── 图表/ └── scripts/ └── export_report.py这样 notebook 文件与数据文件、输出文件分开避免同一个目录下文件越来越多。10.2 每次新建 notebook 先做小测试复杂任务开始前先在一个空单元格里执行print(ok)确认内核正常。然后逐步增加代码。这样能把“环境问题”和“代码问题”分开排查。10.3 及时保存并定期做检查点Notebook 默认会自动保存但自动保存间隔不是无限短。做长时间分析前先手动Ctrl S保存一次。如果代码运行时间很长建议先把中间结果导出到 CSV避免内核崩溃时全部丢失。10.4 分享前清空输出如果你要把 notebook 发到 GitHub 或发送给同事建议先清空输出保留代码结构和 Markdown 说明。清空输出的操作是Edit - Clear All Outputs。这样文件体积更小也能避免意外泄漏运行过程中产生的敏感信息。10.5 涉及敏感数据的合规提醒如果 notebook 中处理的是客户数据、业务报表、人脸照片、语音样本或其他受保护信息务必注意以下几点不在明文代码中硬编码账号密码、Token、数据库连接串。不把包含敏感信息的 notebook 直接发送给无关人员。在真实业务数据上测试模型或脚本之前先在脱敏数据上验证。发布到外部平台前检查输出内容和图表是否包含个体级别信息。10.6 环境隔离多个数据分析项目建议使用独立环境。一个项目一份依赖清单可以用pip freeze requirements.txt导出别人拿到后执行pip install -r requirements.txt就能复现环境。如果使用 conda推荐写死主要依赖版本避免时间久了包版本漂移导致结果不可复现。11. 总结与下一步Jupyter Notebook 最值得尝试的点是它足够轻量装好 Python一条命令启动浏览器打开就能写代码、画图、写文档。它对初学者非常友好对数据分析师和算法工程师来说又是日常标配工具。值得最先验证的功能是单元格执行、Markdown 渲染、matplotlib 画图和 nbconvert 导出。这四步全部走通你就有了一套完整的数据分析工作台。最容易踩的坑是环境变量没有配置好导致jupyter命令找不到其次是端口被占用导致启动失败第三是内核连接不上。这三个问题都不难解决你只需要记住一个万能入口python -m jupyter notebook。它能绕开大部分 PATH 问题先把服务跑起来再说。后续可以继续扩展的方向有三条一是深入学习 JupyterLab 和 VS Code 的远程开发模式把 notebook 放到服务器上跑二是掌握 Papermill 等参数化执行工具把固定流程变成自动报告三是学习用 nbconvert 把 notebook 发布成博客或技术文档。这些都是在 Jupyter Notebook 基础之上的进阶能力等基础功能熟悉后自然会用到。如果你还没装好 Jupyter Notebook建议现在先执行一次pip install jupyter notebook再启动一个空白笔记本测试。真正让工具发挥价值的不是看完这一篇而是打开浏览器亲手把第一个单元格跑通。