入行这几年Jupyter Notebook 我一直当主力交互环境用数据清洗、公式验证、甚至写博客草稿都在里面完成。但说实话大部分人在安装和插件这件事上都是靠百度碎片拼出来的今天搜一条安装命令明天搜一个插件名装完发现环境乱了、插件勾选不生效、默认保存路径改半天没用。这篇我把自己实际踩过的路线完整理一遍从安装形态怎么选到插件体系怎么用再到保存路径和排错细节尽量让不同基础的读者都能照着操作少在配置上耗时间。1. 先把安装路线想明白不同折腾法的取舍很多人一上来就在终端里敲pip install jupyter notebook敲完也能用但后面装插件、管理 Python 包的时候才意识到问题往往出在最开始的安装方式上。Jupyter Notebook 本身只是一个前端壳子真正的执行环境是后面的 Python 解释器和 Kernel所以安装形态决定了你后面所有操作的顺畅程度。我见过的安装方式大致分三类。第一种是 Anaconda 全家桶把 Python、conda、常用科学计算库、Jupyter 全部装到一个大目录里。好处是真的省心装完基本开箱即用适合完全不想碰命令行的新手。坏处也明显体积好几个 G而且 Anaconda 自带的 Python 很容易和系统里原有的 Python 打架尤其在国内开发机上经常出现 明明装了这个包导入时却说找不到 的灵异问题。第二种是 Miniconda conda 环境我只装conda本体然后按项目建虚拟环境在环境里分别装 Jupyter 和依赖。这种方式我强烈推荐给做数据分析或需要隔离项目依赖的人。它比 Anaconda 轻得多但保留了一样的环境管理能力。第三种是纯系统 Python venv pip适合只在某一个项目里临时用 Jupyter、不搞复杂多环境的读者。优点是干净不引入 conda 的包管理系统缺点是底层依赖出问题时要自己处理。三种方式的适用场景我整理了一个对比安装方式适合人群优点主要的坑Anaconda新手、不想管环境开箱即用体积大、易与系统Python冲突Miniconda conda数据分析、多环境开发者轻量、环境隔离干净需要自己装常用库venv pip临时使用、追求极简轻量、与系统隔离底层依赖问题需手动处理我自己现在的主力组合是 Miniconda每个项目单独一个环境Jupyter 装在项目环境里配合 kernel 注册机制后面细说可以做到每个环境对应一个 Notebook kernel。这样你在不同项目之间切换时Notebook 内核列表里一目了然不会因为装错环境把整个系统搞挂。2. 从零到能跑核心安装命令与启动验证2.1 Conda 环境的建立与 Jupyter 的安装不管你有没有装过 Anaconda我都建议先用 Miniconda 重新梳理一遍环境。去官网下载对应系统的 Miniconda 安装包安装过程一路默认即可。装完以后先在终端里建一个专门跑 Jupyter 的环境这一步我给完整命令# 创建环境python 版本建议用 3.9 或 3.11兼容性最稳 conda create -n jupyter_env python3.11 -y # 激活环境 conda activate jupyter_env # 安装 Jupyter 本体 conda install -c conda-forge jupyterlab -y conda install -c conda-forge notebook -y这里我同时装了 JupyterLab 和经典 Notebook很多人会疑惑为什么两个都装。理由很简单JupyterLab 是现在的主流交互界面功能强、插件体系新但经典 Notebook 依然有大量老插件和教程基于它运行两个都留着方便对照也方便从旧项目过渡。conda 安装的好处是它会把 Node.js、zeromq 这类底层依赖一并处理好后面装插件会省很多麻烦。如果你更习惯用 pip也可以用下面的命令python -m pip install --upgrade pip python -m pip install jupyterlab notebook注意 Windows 下如果提示 jupyter 不是内部或外部命令原因通常是当前环境的 Scripts 目录没有加入 PATH。用conda activate jupyter_env激活环境后一般能解决实在不行再用python -m jupyter这种模块方式启动。2.2 验证与配置生成配置文件、启动、检查端口安装完成后不要急着打开网页乱点先做两步验证。第一步在终端里运行jupyter --version能输出各组件版本信息说明基础没问题。第二步执行一次启动jupyter notebook # 或者 jupyter lab正常情况下终端会打印出一串信息并自动打开浏览器。如果没有自动打开把终端里显示的http://localhost:8888/tree或http://localhost:8888/lab手动粘贴进浏览器即可。这个细节经常有人卡住浏览器打不开不一定是你安装失败更常见的是端口被占用或者浏览器默认设置拦截了跳转。端口问题很好排查终端里注意看有没有这样一行The Jupyter Notebook is running at: http://localhost:8888/如果这里显示的端口是 8889 或别的说明 8888 被占用了直接用显示的端口访问就行。想固定端口可以用jupyter notebook --port8888 --no-browser--no-browser的意思是启动时不自动弹浏览器适合你在服务器上跑 Jupyter 然后用本地浏览器远程访问的场景。这些基础参数后面配置默认保存路径时还会用到建议记一下。生成配置文件这一步很多人会漏掉但它几乎是所有后续配置的基础jupyter notebook --generate-config这会在当前用户的.jupyter目录下生成一个jupyter_notebook_config.py文件默认保存路径、启动参数、服务器配置都写在这里。Windows 上路径通常是C:\Users\你的用户名\.jupyter\jupyter_notebook_config.pymacOS/Linux 是~/.jupyter/jupyter_notebook_config.py。后面讲修改默认保存路径时我们就是改这个文件里的字段。3. 插件安装的真正入口经典 Notebook 与 Lab 两套机制3.1 经典 Notebook 的 nbextensions 插件体系经典 Notebook对应jupyter notebook命令的插件机制靠的是 nbextensions核心工具是jupyter_contrib_nbextensions。这个工具包含几十个经典扩展比如目录大纲、代码格式化、变量查看器、自动缩进等安装命令也比较固定# 安装扩展集合 pip install jupyter_contrib_nbextensions # 将扩展文件复制到 Jupyter 的静态资源目录 jupyter contrib nbextension install --user # 启动 Jupyter Notebook jupyter notebook启动后在 Notebook 首页上方会多出一个 Nbextensions 标签页进去就能看到所有可勾选的扩展列表。勾选生效后刷新页面即可。我自己必开的几个Table of Contents自动生成 Markdown 标题目录长文档导航神器Autopep8单元格代码一键格式化Variable Inspector查看当前 Kernel 里所有变量的类型和值Collapsible Headings折叠标题适合组织结构化笔记Notify代码跑完时桌面通知跑长任务时不用一直盯着页面这里有一个重要的版本警告Notebook 7.x 发布后采用了 JupyterLab 的前端架构那套 nbextensions 的注入机制基本失效Nbextensions 标签页也看不到了。如果你装的是最新版 Notebook比如 7.x用上面的命令能装上扩展但页面里不会有勾选入口。我的建议是还在用经典 Notebook 且离不开这些扩展的可以把 Notebook 固定到 6.x 版本pip install notebook7或者直接切到 JupyterLab用下面要讲的现代扩展体系。这也是为什么我在前面的安装步骤里同时装了两者切换成本低。3.2 JupyterLab 的现代扩展体系JupyterLab 的插件体系跟经典 Notebook 完全不同它基于 npm 和 Node.js插件通过jupyter labextension install或 pip 包两种方式安装。新版 JupyterLab3.x 及更高大力推行 pip 安装方式很多官方扩展直接pip install即可省去 Node.js 编译的麻烦。安装扩展之前先确认环境里有没有 Node.js因为有些老扩展重建前端时需要它。终端里运行node -v没有输出就去下载安装 Node.js LTS 版本。不过我现在更推荐优先选支持 pip 安装的扩展# 目录大纲jupyterlab-toc 其实已内置于Lab无需额外装 # 代码格式化 pip install jupyterlab_code_formatter # 变量查看器 pip install lckr-jupyterlab-variableinspector # Git 集成需要Node支持 pip install jupyterlab-gitJupyterLab 常用的插件清单我在下面列出基本覆盖了日常高频需求插件用途安装方式jupyterlab_code_formatter代码格式化支持black/isortpip installjupyterlab-gitGit 面板pip installjupyterlab-lsp代码补全、跳转、诊断pip installjupyterlab-spellcheckerMarkdown 拼写检查pip installjupyterlab/toc目录大纲内置或扩展jupyterlab-aiAI 对话、代码生成pip install安装完 pip 扩展后一般不需要手动 rebuild新版 JupyterLab 在启动时会自动重建前端。但如果你碰到了界面没有变化的情况手动执行一次重建即可jupyter lab build这个命令会重新编译前端资源耗时几分钟属于正常现象。完成后重启 JupyterLab 才能看到新插件。3.3 高价值插件清单与安装指令我把两个体系里真正值得装的插件合并成一段实操说明方便直接复制。如果你是全新环境推荐按下面的顺序操作# 经典 Notebook 插件仅兼容 Notebook 6.x conda activate jupyter_env pip install jupyter_contrib_nbextensions jupyter contrib nbextension install --user # JupyterLab 插件 pip install jupyterlab_code_formatter jupyterlab-lsp jupyterlab-git # 代码格式化后端工具jupyterlab_code_formatter 需要依赖它们才真正生效 pip install black isort装完jupyterlab_code_formatter后必须安装 black 和 isort否则插件有界面但没有实际格式化引擎这在官方文档里写得不明显我当初装完发现点击格式化提示 No formatter installed 才明白。这类装了主插件还要装后端工具的情况非常典型记不住就多看插件报错信息它能帮助你定位缺失的依赖。另外如果你做数学公式相关的工作可以在 Markdown 单元格里用$x^2$和$$\int_0^1 f(x) dx$$渲染 LaTeX 公式Jupyter 自带的 MathJax 已经支持不需要额外插件。遇到公式渲染错位时先刷新页面再检查是否有多个扩展同时修改了渲染器这类冲突比公式本身难查得多。4. 顺手把默认保存路径改对少走三年弯路Jupyter Notebook 的默认保存路径可能是被问得最多的一个问题热词里也有jupyter notebook默认保存路径的身影。大部分人的操作是在界面里一个个切换目录麻烦还容易忘。正规做法是去改配置文件。先再次确认已经执行过jupyter notebook --generate-config然后用文本编辑器打开生成的jupyter_notebook_config.py找到这一行# c.NotebookApp.notebook_dir 把它改成你自己的目标目录。Windows 系统下记住用正斜杠不要用反斜杠这基本是新手改配置必踩的坑c.NotebookApp.notebook_dir D:/MyNotebooksLinux/macOS 下则直接写绝对路径c.NotebookApp.notebook_dir /home/username/notebooks改完保存重启 Jupyter Notebook进入页面后地址栏显示的根目录应该是你设置的那个路径。如果你用的是 JupyterLab新版配置字段稍有变化需要在同一个文件里加一行c.ServerApp.root_dir D:/MyNotebooks我这里写了两个字段原因在于 Jupyter 近几个版本中NotebookApp.notebook_dir用于经典 NotebookServerApp.root_dir用于统一服务器尤其是 JupyterLab。两个都写上也不会互相干扰属于稳妥打法。如果你只是临时想把这一次会话的目录改一下不需要改配置文件直接启动时加参数jupyter notebook --notebook-dirD:/MyNotebooks jupyter lab --ServerApp.root_dirD:/MyNotebooks还有一种小技巧适合 Windows 用户右键 Jupyter 的快捷方式在目标一栏的末尾加上引号和上面的参数双击就是指定目录启动不污染全局配置。注意参数和前面的启动路径之间要有空格整个目标用英文双引号封起来。提示改完配置文件之后旧的终端界面可能不会立刻生效。Windows 上还容易出现配置被缓存的情况直接重启终端再启动 Jupyter比在同一个窗口反复试更有效。5. 最容易翻车的几个安装坑以及完整的排查链路5.1 经典案例Notebook 7 升级后 nbextensions 全部失效这个坑我在前面章节预警过也是后台收到咨询最多的一种情况用户执行pip install notebook之后启动发现首页压根没有 Nbextensions 标签所有勾选的插件全部消失。这不是你没装好而是 Notebook 7 的前端架构变了老扩展的注入机制不再被支持。排查链路记录下来供参考先确认 Notebook 版本运行jupyter notebook --version如果输出以 7 开头老插件失效是正常的。接着查看环境是 JupyterLab 还是经典 Notebook终端里启动jupyter notebook后看地址后缀是/tree还是/lab。/lab说明前端是 JupyterLab。最后根据需求选一个方向要么pip install notebook7降级到 6.x 保住 nbextensions要么接受新架构改用 JupyterLab 对应的扩展体系。我的建议是优先走 JupyterLab 方向。老扩展虽多但部分年久失修Node 版本一变就构建失败现代 Lab 扩展的维护活跃度和 API 稳定性明显更好。5.2 权限、插件环境与 kernel 路径问题排查另一个高频坑是jupyter contrib nbextension install时提示权限错误尤其在 Windows 上。命令行报 Permission denied 或者 Failed to copy file to destination 是典型症状。解决方式有两种第一种是在原命令后加--user参数把扩展安装到当前用户目录而不是系统全局目录jupyter contrib nbextension install --user --skip-running第二种是检查是否同时运行了多个 Jupyter 进程。扩展安装和复制静态文件时正在运行的 Jupyter 可能锁定部分目录导致安装写入失败。先把所有 Jupyter 窗口关掉再执行安装命令最后重新启动。和插件环境并列的大坑是 kernel 路径错乱。很多初学者在 A 环境装 Jupyter又在 B 环境装了 pandas进入 Notebook 后import pandas报错。原因是 Notebook 默认使用启动它的 Python 环境作为 Kernel不会自动切换到你激活的另一个环境。解决办法是显式注册 kernel# 在 B 环境里执行 conda activate B python -m ipykernel install --user --name B --display-name Python (B)重启 Jupyter 后新建 Notebook 时就能看到 Python (B) 这个内核选择它就能正确访问 B 环境的包。这个操作非常实用尤其是用 conda 管理多个项目时一套 Jupyter 对接所有环境。还有一类问题是 Node.js 导致的 Lab 扩展安装失败。如果你在jupyter labextension install时看到 npm ERR 或者 Command npm not found基本就是环境缺少 Node.js。先去官网装一个 LTS 版本再重新执行安装。新版 JupyterLab 虽然很多插件可走 pip 路径绕开 Node.js但碰上必须要labextension install的扩展这个依赖躲不掉。最后补充一个很多人忽略的小问题浏览器插件拦截导致 Notebook 页面加载不完整。如果你装有去广告、脚本管理类浏览器插件遇到页面空白或按钮不响应时把 localhost 站点加入白名单再试一次。这个点很少有人往那方面想但实际频率不低。最后留一个个人建议Jupyter 的插件生态这两年变化很快版本之间的不兼容是整个社区共同面对的问题。我现在的习惯是固定一个小版本号比如 Notebook 6.5.x 或 JupyterLab 4.x不要随手 latest 升级等需要新功能时再统一迁移。安装插件前养成在终端里先查版本的习惯能省掉后续至少一半的排错时间。我的做法就这么多把基础路线捋顺插件和路径配置自然就不容易翻车。