第一次用 Jupyter 的人通常会遇到两个纠结装哪个版本启动后写代码和普通 Python 文件到底有什么区别。Jupyter 本质是一套基于 Web 的交互式开发环境核心不是编辑器本身而是“代码、说明、运行结果放在同一个文档里”的工作方式。你可以把它当成一本可以执行的技术笔记写完一段代码立刻看到输出还能配上 Markdown 说明最终整个文档可以导出成网页、PDF 或普通 Python 脚本。这次我们来看 Jupyter 的安装、启动、两个主要界面Notebook 和 Lab的区别、日常代码操作怎么写以及最容易碰到的几个报错怎么处理。如果你之前只听说过 Jupyter但没系统跑通这篇文章可以直接跟着做一遍。1. Jupyter 核心能力速览能力项说明项目类型交互式开发环境支持 Python、R、Julia 等多种内核核心功能单元格运行代码、Markdown 混排、数据可视化、文档导出、远程访问启动方式命令行启动通过浏览器访问主要界面经典 Notebook 和 JupyterLab 两种硬件要求普通电脑即可不依赖 GPU占用主要是内存和 CPU是否支持 API较新版本提供 Jupyter Server REST API具体端点以本地版本为准是否支持批量任务不擅长常驻批量队列可结合 nbconvert、papermill 做离线批量执行适合人群数据科学、深度学习调试、教学演示、算法快速验证、技术笔记常见问题命令找不到、启动失败、浏览器空白、内核连接失败、端口占用从上面的表格能看出来Jupyter 的定位是“交互式探索”而不是生产级服务。它的价值在于让你把想法快速写成代码立刻看到效果并且把过程记录下来。下面先从安装开始。2. 适用场景与使用边界Jupyter 最适合的场景是数据分析、机器学习实验、教学课件和算法原型。比如你拿到一份 CSV想快速做清洗、统计、画图Jupyter 的单元格设计就非常合适一段代码处理数据下一段代码展示结果旁边再用 Markdown 写分析结论整个过程是渐进式的。深度学习场景下Jupyter 也常用于调试模型、可视化 loss 曲线、查看中间结果。但 Jupyter 并不是万能的。它不适合做生产 API 服务不适合跑大规模并行计算也不适合作为长时间运行的定时任务。原因在于 Notebook 的文件结构基于 JSON把代码、输出、元数据混在一起代码版本控制时 diff 很痛苦同时它的执行状态保存在内存里一旦内核崩溃前面的变量全部丢失不方便做故障恢复。还有一个容易被忽视的问题Notebook 单元格是共享同一个全局命名空间的前面的代码定义了变量后面的代码可以直接用但这也意味着执行顺序一旦乱掉结果就可能不可复现。团队协作时如果每个人都在不同顺序下运行过单元格最终导出的结果可能各不一样。所以在正式项目里通常把 Jupyter 当“草稿本”用验证通过后再整理成 .py 脚本进入工程流程。涉及敏感数据、API 密钥时也要避免直接把密钥写进单元格因为 Notebook 一旦分享出去密钥也就泄露了。3. Jupyter 环境准备与安装3.1 检查 Python 环境Jupyter 本身是一个 Python 包安装前先确认电脑上有没有 Python。Windows 下打开命令提示符或 PowerShellmacOS/Linux 打开终端执行python --version正常情况下会输出 Python 版本号比如Python 3.11.5。如果提示“python 不是内部或外部命令”说明 Python 没装或者没有加入 PATH需要先安装 Python并在安装时勾选“Add Python to PATH”。3.2 使用 pip 安装 Jupyter安装经典 Notebook 和 JupyterLab 可以分开装。最简单的做法pip install jupyter这条命令会安装 Jupyter Notebook 相关的核心组件。如果需要 JupyterLab再执行pip install jupyterlab如果下载速度慢可以临时用国内镜像源pip install jupyter -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后验证是否成功jupyter --version能看到版本信息说明命令行工具已经可用。这里要注意pip 安装的脚本一般会进入 Python 的Scripts目录如果安装后依然提示“jupyter 不是内部或外部命令”多半是Scripts目录没有加入 PATH。3.3 使用 Anaconda 安装 Jupyter如果你装的是 AnacondaJupyter 通常已经内置。Anaconda 自带的版本比较齐全包括 Notebook、Lab 和常用数据科学包。在 Anaconda Prompt 中执行conda install jupyter也可以只安装 Notebookconda install jupyter notebookAnaconda 的价值在于环境管理你可以为不同项目创建独立的 Python 环境避免包冲突。创建一个新环境并安装 Jupyterconda create -n myenv python3.11 conda activate myenv pip install jupyterlab3.4 虚拟环境与 Jupyter 内核绑定很多人在某个 conda 环境里安装了 Jupyter启动后发现新环境中安装的包在 Notebook 里导入不到。根本原因是 Jupyter 默认运行的 Python 内核是启动时所在环境的内核而不是你新创建的环境。需要手动把虚拟环境注册成 Jupyter 内核。先在目标环境中安装ipykernelpip install ipykernel然后注册内核python -m ipykernel install --user --name myenv --display-name Python (myenv)完成后重启 Jupyter新建 Notebook 时内核列表里会多出一个名为Python (myenv)的选项。这一步卡住的人很多建议新建虚拟环境后第一时间绑定内核免得后面所有包都导不进来。4. Jupyter 启动方式与服务访问4.1 启动经典 Notebook在命令行执行jupyter notebook正常情况下终端会输出一串日志包含本机访问地址和 token。浏览器自动打开http://localhost:8888/tree页面这就是 Notebook 的文件管理界面。如果浏览器没自动打开手动复制终端里打印的地址即可。4.2 启动 JupyterLabJupyterLab 是新一代界面启动方式类似jupyter lab访问地址通常是http://localhost:8888/lab。Lab 界面默认显示左侧文件树、中间工作区、底部状态栏更像一个现代化 IDE。4.3 常用启动参数实际使用中以下参数非常常见# 指定端口 jupyter notebook --port 9999 # 启动后不自动打开浏览器 jupyter notebook --no-browser # 允许局域网其他设备访问 jupyter notebook --ip 0.0.0.0 # 指定工作目录 jupyter notebook --notebook-dir D:/projects/jupyter_workspaceJupyterLab 也支持同样的参数把jupyter notebook换成jupyter lab即可。工作目录指定后页面左侧文件树会直接定位到该目录文件管理会清爽很多。4.4 浏览器访问与 Token 机制Jupyter 默认只监听本机地址127.0.0.1其他人无法直接访问。如果要用局域网访问需要设置--ip 0.0.0.0并通过访问地址中的 token 做验证。启动日志里会打印类似http://127.0.0.1:8888/?tokenabc123def456这个 token 相当于登录密码复制完整地址到浏览器即可。别人要访问你的服务时也需要输入对应地址和 token。如果把 Jupyter 暴露到公网一定要设置密码或者使用身份认证否则任何人都能执行代码风险极高。5. Jupyter Notebook 与 Jupyter Lab 区别很多人刚接触时分不清 Notebook 和 Lab经常搜“jupyter notebook lab 区别”。简单说Notebook 是 Jupyter 最早期的经典界面一个浏览器标签页里展示一个.ipynb文档文件树、编辑器、终端都是相对独立的功能。Lab 则是把所有这些功能整合到同一个工作台里支持多标签、多面板、拖拽布局插件生态也更完整。对比项Jupyter NotebookJupyterLab界面布局单文档顶部菜单和工具栏多面板工作台支持分栏和拖拽文件管理需要通过 Dashboard 页面操作左侧文件树可直接拖拽上传多文档同时编辑需要开多个浏览器标签页同一个窗口内多标签切换终端需要另开页面工作台内直接打开终端插件扩展支持但生态较少扩展丰富支持主题、补全、Git 集成代码补全基础补全更完善可安装扩展增强稳定性经典稳定功能多长时间大量文件时资源占用更高从使用体验来说JupyterLab 是 Notebook 的超集功能更现代适合日常开发经典 Notebook 更轻量在老旧电脑或需要极简操作时更合适。如果你在新装环境可以直接上 JupyterLab不必纠结。还有一个常见操作是“jupyter lab 启动后怎么切换目录”。默认情况下Lab 的根目录取决于启动时--notebook-dir指定的路径。出于安全考虑Lab 不允许通过界面直接跳到根目录的上级目录。想换工作目录有几种办法在启动命令中重新指定--notebook-dir然后重启服务。在左侧文件树里点击进入根目录下的子目录但无法跳到根目录之外。如果只是临时打开某个文件可以用“File - Open from Path”输入绝对路径。6. Jupyter 基础操作与代码运行6.1 新建 Notebook在 Notebook 的 Dashboard 页面点击“New - Python 3”或者直接在 JupyterLab 中点击“”选择 Python 3 内核就能新建一个 Notebook。新建后会出现一个单元格默认是 Code 类型可以输入 Python 代码。输入一行代码后按Shift Enter运行。运行结果会直接显示在单元格下方并自动新建下一个单元格。这就是 Jupyter 最核心的使用方式。6.2 单元格类型单元格有三种常用类型Code执行代码支持 Python 等内核语言。Markdown写说明文字支持标题、列表、表格、公式。Raw原样输出内容不执行不渲染。在 Notebook 中通过顶部下拉框切换类型在 JupyterLab 中可以用快捷键或右侧面板切换。实际写分析文档时推荐的做法是一个 Markdown 单元格描述“要做什么”后面 Code 单元格实现“怎么做”这样文档可读性最好。6.3 常用快捷键快捷键能明显提升操作效率最常用的几组Shift Enter运行当前单元格并移动到下一个单元格。Ctrl Enter运行当前单元格不移动。Esc退出编辑状态。Enter进入编辑状态。A在当前单元格上方新建单元格。B在当前单元格下方新建单元格。DD连续按两次 D删除当前单元格。M当前单元格切换为 Markdown。Y当前单元格切换为 Code。Ctrl S保存文件。记忆重点是先按Esc退出编辑状态再按A、B、M、Y才生效。如果你发现快捷键没反应多半是还处于编辑状态。6.4 在 Jupyter 中创建 .py 文件有人问“jupyter 怎么创建 .py 文件”。Notebook 保存的是.ipynb格式但 Jupyter 完全可以创建和执行.py文件。常用做法有三种。第一种在 JupyterLab 中点击左侧“”图标在 Launcher 里选择 Python File会新建一个.py文件。写完代码后保存右键选择 “Run” 就能看到执行结果也可以直接用终端运行。第二种在经典 Notebook 的 Dashboard 页面点击“New - Text File”新建一个文本文件然后把文件重命名为xxx.py即可在 Jupyter 环境中编辑 Python 脚本。文件保存后在 Notebook 里可以用%load把脚本内容加载到单元格%load my_script.py执行后单元格会变成my_script.py的内容。如果只是想运行脚本不查看内容用%run my_script.py第三种在 Notebook 单元格里直接使用%%writefile魔法命令把单元格内容写成.py文件%%writefile demo.py print(hello jupyter) x 10 print(x * 2)运行后会生成一个demo.py文件内容就是单元格里的代码。这种写法适合快速生成脚本再配合%run验证。6.5 魔法命令与系统命令Jupyter 提供了一系列以%开头的魔法命令日常很实用# 统计代码运行耗时 %timeit sum(range(1000)) # 查看当前会话变量 %whos # 执行系统命令注意前面是感叹号 !dir # Windows 查看目录 !ls # Linux / macOS 查看目录 # 运行外部脚本 %run other_script.py%timeit对做算法性能对比特别方便可以快速看到某段代码的执行时间不用自己写重复计时的逻辑。6.6 PyCharm 中使用 Jupyter如果你习惯 PyCharm也可以在 PyCharm 里使用 Jupyter Notebook。PyCharm 专业版对 Notebook 支持较好社区版也能通过配置 Jupyter Server 使用。另一种更轻量的方式是在 PyCharm 安装 Jupyter 插件后用.ipynb文件运行单元格或者直接把.py文件中的代码块用# %%分隔然后右键逐块运行。# %% print(单元格1) # %% print(单元格2)这种方式不需要打开浏览器也能获得类似 Notebook 的分块执行体验。如果你只想做数据分析而不想切来切去这个方案值得试。7. 常见问题与排查方法问题现象可能原因排查方式解决方案jupyter 不是内部或外部命令Python 或 pip 的 Scripts 目录未加入 PATH执行where python、pip show jupyter查看安装位置重新安装 Python 并勾选 Add to PATH或手动添加 Scripts 目录启动失败代码2Windows 下脚本启动器找不到 Python或路径包含空格检查启动命令路径确认 jupyter 脚本指向的 python.exe 存在用python -m jupyter notebook启动或修复 Python 安装Windows 打开后空白浏览器兼容问题、token 失效、内核连接失败查看终端日志换浏览器访问重启内核清除浏览器缓存复制完整带 token 地址重新安装 jupyter端口被占用8888 被其他进程占用终端查看端口占用或换端口启动用--port 9999换端口内核连接失败ipykernel 缺失或版本不匹配检查终端日志重新安装 ipykernelpip install ipykernel --upgrade后重启新建 Notebook 后导包失败虚拟环境未绑定内核检查代码中的内核名称与终端激活环境对比执行python -m ipykernel install --user --name myenv启动后无法切换目录Jupyter 根目录受启动参数限制查看首页地址路径确认根目录用--notebook-dir指定目录后重启下面展开几个高频问题。7.1 jupyter 不是内部或外部命令出现这个提示说明系统找不到jupyter.exe。先确认是否真的安装了pip show jupyter如果显示未安装执行安装命令。如果已经安装问题基本出在 PATH。Windows 下jupyter.exe通常位于C:\Users\你的用户名\AppData\Local\Programs\Python\PythonXXX\Scripts把该目录加入系统 PATH 后重启终端即可。也可以绕开 PATH 问题直接用 Python 模块方式启动python -m jupyter notebook7.2 Windows 启动失败代码 2“启动失败代码2”在 Windows 上很常见通常是 Jupyter 的启动脚本找不到 Python 解释器。可能原因是 Python 安装路径变化或者Scripts目录下的jupyter.exe指向的路径已经失效。排查时可以先运行where jupyter然后检查安装目录下有没有python.exe。最稳妥的修复方式是重装 Python或者用python -m jupyter notebook启动。如果项目里有多个 Python 版本建议在虚拟环境里重新安装 Jupyter。7.3 Windows 打开后空白浏览器打开 Jupyter 后一片空白可能是 ZMQ 组件问题、浏览器兼容问题或内核启动失败。先看启动 Jupyter 的终端窗口有没有报错信息如果提示ModuleNotFoundError: No module named zmq执行pip install pyzmq。也可以尝试换一个浏览器访问有时 Chrome 插件会拦截本地页面换 Edge 或 Firefox 就能显示。7.4 端口占用与进程残留如果多次启动 Jupyter经常会出现端口被占用的情况。启动时报错Address already in use说明 8888 端口已经被之前的进程占用。Windows 下可以用netstat -ano | findstr 8888查看占用进程然后在任务管理器结束对应进程或者换个端口启动。8. Jupyter Server API 与自动化调用Jupyter 不只是图形界面较新版本的 Jupyter Server 提供了 REST API可以用来管理内容、创建内核和执行代码。这意味着你可以通过 HTTP 请求在 Jupyter 环境中自动运行代码适合做一些远程触发、自动化演示或简单批处理场景。具体接口路径和参数会随版本变化下面给出一个通用模板使用前查询本地版本的 API 文档。首先确认服务已启动jupyter notebook --no-browser --port 8888然后可以在 Python 中调用。以下示例用于获取 Jupyter 根目录下的文件列表import requests base_url http://127.0.0.1:8888 token 你的token # 获取根目录内容 resp requests.get( f{base_url}/api/contents, params{token: token}, timeout10 ) if resp.status_code 200: for item in resp.json()[content]: print(item[name], item[type]) else: print(请求失败, resp.status_code, resp.text)如果需要在自动化脚本中启动 Jupyter也可以提前把 token 写在配置里避免每次复制。但要注意token 相当于访问凭证不要提交到公开代码仓库。关于批量任务Jupyter 并不是一个队列系统不建议把长时间运行的批量任务直接挂在 Notebook 里等待执行。更可靠的做法是把逻辑写成.py脚本用调度工具定时执行如果确实希望批量执行多个.ipynb可以使用 nbconvert 的--execute参数jupyter nbconvert --to notebook --execute --inplace analysis.ipynb这条命令会重新执行analysis.ipynb并把结果写回原文件。也可以批量处理一个目录下的文件for f in notebooks/*.ipynb; do jupyter nbconvert --to notebook --execute --inplace $f done更复杂的参数化批量执行可以试试 papermill。它允许给同一个 Notebook 传不同参数自动生成多份输出结果。如果你经常要跑多组实验用 papermill 比手工改单元格参数要省心得多。9. 最佳实践与使用建议第一用虚拟环境隔离开项目依赖。Jupyter 本身很轻但项目里可能用到不同版本的 pandas、numpy、torch如果不隔离升级一个包就可能搞坏另一个项目。第二把 Notebook 当草稿把.py脚本当交付物。数据分析探索期用 Notebook 快速验证验证通过后把关键逻辑整理成模块化脚本方便测试和部署。这样做既能保留探索过程的记录又不会让代码全部堆在一个 JSON 文件里。第三注意执行顺序。Notebook 的变量在内存中共享单元格执行顺序不同结果可能不同。每次重新分析数据前建议点击“Kernel - Restart Run All”确保从头到尾按顺序执行一遍避免出现上个单元格残留变量影响下个结果的情况。第四控制单元格大小。一个单元格不要写几百行代码太长既难调试又难阅读。一个单元格只做一件事读数据、清洗、画图、建模。中间需要解释说明时用 Markdown 单元格分隔。第五敏感信息不入库。数据库密码、API Key、OAuth Token 不要直接写在 Notebook 里。可以把配置放到环境变量或.env文件里Notebook 中通过os.environ读取避免分享文档时泄密。第六检查代码规范。可以在 Notebook 里用系统命令调用代码检查工具!flake8 my_script.py !black --check my_script.py如果没安装先执行pip install flake8 black。这类工具能发现未使用的变量、行过长、格式问题适合在把脚本提交到团队仓库之前跑一遍。第七合理管理文件目录。建议把 Notebook、数据、输出结果分开存放。启动 Jupyter 时用--notebook-dir指向项目根目录然后在项目内部分notebooks/、data/、outputs/。左侧文件树看起来清晰后续备份和 git 管理也方便。10. 总结与下一步Jupyter 最值得花时间掌握的不是某个花哨功能而是“运行一个单元格、立刻看到结果、随时补充说明”这套交互节奏。装好环境后建议先验证三件事能不能用jupyter lab正常启动新建的 Notebook 能不能运行print和%timeit以及在项目目录下能不能用%%writefile生成.py文件。这三项通了日常使用就基本没有障碍。最容易踩的坑集中在环境层面命令找不到、虚拟环境没绑定内核、端口被占用。这些问题的排查思路都不复杂核心是看终端日志先确认路径和环境再处理功能问题。后续可以继续往三个方向扩展第一学习如何把 Notebook 导出成报告或幻灯片让分析结果更容易展示第二尝试在 JupyterLab 里安装 Git 插件把开发流程和版本管理串起来第三如果需要批量实验用 papermill 参数化 Notebook比自己反复复制粘贴参数要高效得多。建议先把这篇的基础操作跑一遍收藏备用后面遇到问题时回来对照排查。