蓝盐泳池1983Jupyter Notebook的安装，网上教程一抓一大把，但我敢说大多数人都是照着别人的步骤敲了一遍，然后在自己电脑上报错，回头再找原因，发现根本不知道该查哪。我自己也经历过这个阶段，装完一遍之后才发现，真正的问题根本不在于“安装命令”本身，而是安装前的那堆准备工作——你的电脑里到底有什么环境，哪些命令能用，哪些版本匹配，这些才是决定成败的关键。
这篇分享我不会只教你敲两行命令，而是把整个“从零开始装到能正常用、能舒服用”的链路完整走一遍。文章覆盖安装前的环境自查、不同平台下的安装方式、最让人头疼的“subprocess-exited-with-error”这类报错的完整排查思路、首次启动后的基础操作，以及很多人都会问的“侧边栏如何显示标题总览”和“目录插件怎么装”这两个实用需求。无论你是刚接触Python的纯新手，还是以前装了一半卡在某个问题上的人，按照这篇的顺序走，基本上都能解决大部分问题。
1. 别着急输命令：我先说点安装前必须想清楚的事
很多人拿到教程第一步就是打开终端复制安装命令，这恰恰是后面出问题的根源。Jupyter Notebook本身不是一个独立的软件，它运行在Python环境之上，你的电脑里Python装得怎么样、装了什么版本、用的是虚拟环境还是全局环境，这些都会直接影响安装结果。
1.1 用不用Anaconda，不要凭感觉选
关于Anaconda和Jupyter的关系，我用一句话讲清楚：Anaconda是一个Python的集成发行版，它把Python解释器、常用科学计算库、包管理器conda，以及Jupyter Notebook这一系列工具都打包好了一起给你。也就是说，装了Anaconda，其实Jupyter Notebook是附带的，你基本不需要再单独折腾安装。
但Anaconda的缺点是太庞大，新版装完少说好几个G，里面很多包你可能永远用不到。所以现在更多人倾向于用Miniconda或纯Python环境去安装。Miniconda就是Anaconda的精简版，只包含conda和Python，后面需要什么再装什么，干净利落。
而如果你已经单独装了Python，那直接用pip安装Jupyter Notebook是最快的方式。这里没有唯一正确答案，选择标准很简单：
| 方案 | 适合场景 | 缺点 |
|---|---|---|
| 完整Anaconda | 完全新手，不想理解环境管理，想开箱即用 | 体积大，冗余多 |
| Miniconda | 能接受命令行操作，想轻量但保留conda便利性 | 需要自己装Jupyter |
| pip + Python | 已经有了Python环境，或偏好最小化安装 | 对新手来说环境隔离要额外注意 |
| Docker镜像 | 不想污染本地环境，想要可复现环境 | 桌面端使用不直观，有学习成本 |
如果你问我的建议，纯新手直接从Miniconda开始比较合适。它没有Anaconda那么臃肿，但conda后面帮你创建隔离环境的时候是真的省心。
1.2 理解“环境隔离”这回事，而不是装到一个篮子里
做Python开发超过半年的人，基本都遇到过“这个包升级之后别的项目跑不了”的糟心事。Jupyter Notebook也是Python生态里的一分子，它依赖一堆底层库，比如ipykernel、jupyter-core、nbformat，一旦这些依赖和系统里已有的包的版本产生冲突，安装就会报错，或者装完了启动时各种莫名其妙的崩溃。
所以我的习惯是，打开终端之后先检查一下你现在处于哪个Python环境里。Windows上在cmd或PowerShell执行：
bash复制where python
macOS或Linux执行：
bash复制which python
如果输出路径带着anaconda或者miniconda的字样，说明你已经在conda环境下。如果输出是/usr/bin/python或C:\Pythonxx，说明你用的是系统级Python。
知道自己在哪个环境，是为了防止你辛辛苦苦装了半天，结果装到了一个你不常用、甚至权限受限的环境里，后面打开Jupyter又找不到内核，但你自己还没意识到。
还有一种情况特别值得提醒：Windows用户喜欢直接从微软商店安装Python。商店版Python会自带一个禁用的别名机制，有时候你在终端输入python，弹出的不是解释器，而是商店页面。装Jupyter前最好先关掉“应用执行别名”里的这两个开关，否则后续会很折腾。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 从零到真正能用：安装过程的分步实测
确认好环境信息后，开始装。为了方便对照，我分两种情况说明：用conda和用pip。
2.1 conda或Miniconda环境下的安装步骤
如果你装了Miniconda，打开Anaconda Prompt（Windows会自动有这个入口），或者终端里确保conda命令可用后执行：
bash复制conda create -n jupyter-env python=3.9 -y
conda activate jupyter-env
conda install jupyter notebook -y
先创建环境再安装，这个习惯能帮你把Jupyter相关的东西全部收拢在一个独立环境里，之后不管怎么折腾都不会影响到系统底层的Python。
创建环境这一步为什么值得强调？我见过很多人在base环境里直接装，后面又因为别的项目创建了新环境，两边的包互相干扰，最后连Jupyter都启动不了。独立环境就像给每个项目隔了一个单间，住着清净。
等conda跑完，直接输入：
bash复制jupyter notebook
正常情况下终端会输出启动日志，然后自动打开浏览器。如果这一步成功了，那这一段你可以直接跳过。
2.2 纯Python环境下的pip安装步骤
用pip之前，先确保pip本身是新的。这一步是很多奇怪报错的隐藏来源，我在排查问题的时候经常发现，报错的人pip版本还是好多年前的，旧pip在解析依赖的时候能力弱，容易出错。
bash复制python -m pip install --upgrade pip
升级完pip，再安装Jupyter Notebook：
bash复制python -m pip install jupyter -y
这里我用的是python -m pip而不是pip。这两个有个区别值得你记住：python -m pip确保你用的pip和当前运行的python绑定在一起，而直接输pip有可能会调用到另一个环境里的pip。既然前面已经确认过环境了，用python -m pip会更严谨。
安装完成后验证是否成功：
bash复制jupyter --version
python -m pip show notebook
第一个命令能看到Jupyter的核心组件版本，第二个命令确认notebook这个包自身有没有装好。能看到版本信息，说明主体已经没问题了。
2.3 如果你只想用网页版而不想在本地折腾
还有一种使用场景，你只是临时想用一下Notebook，或者你对命令行有天然恐惧，那直接用浏览器打开jupyter.org/try，在网页上体验即可。它不需要本地安装，打开就能编辑运行Python代码。
要注意的是，网页版的数据和运行环境都在对方服务器上，不适合放任何重要代码或数据，拿来学习语法、体验功能没问题，正经开发必须回到本地环境来。
2.4 为什么我推荐给笔记本内核单独配一个ipykernel
有些场景下，你可能不希望一直待在自己创建的conda环境里，而是想让Jupyter能选择不同环境的内核。这就需要手动把环境注册给Jupyter：
bash复制conda activate myenv
python -m pip install ipykernel
python -m ipykernel install --user --name myenv --display-name "Python (myenv)"
--name是内核在配置文件里的唯一标识，--display-name是你在Jupyter界面中看到的名字。注册完之后，Jupyter新建Notebook时就能在下拉框里看到“Python (myenv)”这个选项。这个操作不难，但能极大提升你后面管理多环境的使用体验，建议提前搞明白。
3. 拦路最多的报错：subprocess-exited-with-error到底是什么意思
如果你是在执行pip install的过程中报了这个错，先不要冲动地重装一遍或者换一个Python版本。这个报错的意思是：pip在安装某个包时，调用了一个子进程来执行安装脚本，子进程跑完发现退出码不是0，pip就把错误归类为subprocess-exited-with-error，然后把子进程的输出贴给你看。
说人话就是：你要装的东西里面有某个依赖不是简单的拷贝文件，而是需要现场编译，编译过程挂了。
3.1 常见根因之一：包需要编译但缺少编译工具
以Windows系统为例，很多科学计算包的重要版本会提供预编译的wheel文件，你直接装没毛病。但如果这个包没有windows对应的wheel，或者你用了一个比较新的Python版本，PyPI上还没有匹配的wheel，那pip就只能从源码去构建。构建过程中可能依赖MSVC编译环境或者MinGW，你没有装，构建就直接失败。
解决思路有两个：第一是不要死脑筋装最新版Python，优先使用那些主流包已经适配好的Python版本，比如Python 3.9到3.11都算稳妥区间。第二是去对应包官网下载.whl文件手动安装，而不是非要让pip从源码现场编译。
3.2 常见根因之二：网络问题导致依赖下载不完整
如果你处在网络环境不太稳定的情况下，pip下载大包的时候文件中途断了，也会造成后面解压或者构建失败。这种情况报错信息里经常会出现“Download error”或“Transmission timeout”之类的字眼。
一个有效的做法是在安装命令后面加上超时时间的限制和镜像源，把下载这关稳住了，后面报错的概率会立刻下降。假设你在国内网络环境，直接用PyPI官方源有时候确实很慢，换一个镜像源更实际：
bash复制python -m pip install jupyter -i https://pypi.tuna.tsinghua.edu.cn/simple --timeout 120
这里用清华镜像的源，--timeout 120的意思是每个包下载如果超过120秒没有响应就重试，而不是无休止等下去。镜像源和超时参数一起用，能解决大部分因为网络不稳导致的构建失败。
提示：如果你用了公司的内网，访问外网PyPI本来就受限，那么用镜像源可能也没用，需要问下网络管理员有没有内网PyPI代理。
3.3 逐行读报错的排查链路
遇到subprocess-exited-with-error，不要只看最后两行。正确的排查流程是这样：
- 往上翻日志，找到第一次出现红色或者高亮“error”的行，那一行通常描述了真正失败的动作。
- 如果看到“Failed building wheel for xxx”这样的内容，说明是xxx在构建wheel阶段失败了。
- 紧接着往上看，看有没有“ERROR: Could not find a version that satisfies the requirement xxx”，如果有，说明是版本解析找不到匹配项。
- 不是版本问题，再检查是不是本机缺了编译器或依赖库。
- 最后再看是不是下载环节本身有网络问题。
我举一个自己遇到过的真实案例：某次在新安装的Linux云主机上执行pip install jupyter，报了subprocess-exited-with-error，前面的日志里显示是pyzmq构建出错。原因就是这台云主机缺了build-essential和python3-dev这两个基础包，c扩展没法编译。装完这两个包再执行安装，一路畅通。所以报错不可怕，找到第一个真正的错误点，问题就解决了一半。
如果实在着急用，还有一条备用路径：直接安装预编译的包集合。Anaconda或Miniconda本来就是带了一堆预编译包，由于conda使用了特定的渠道进行二进制分发包，很多pip上需要现场编译的场景在conda里就省掉了。所以同样这个报错，换conda安装大概率能绕过去，这也是我为什么建议新手可以考虑Miniconda。
3.4 一个容易被忽略的坑：以管理员权限运行终端
如果你是Windows用户，那请记住这句话：安装Python包时，如果提示权限不足（permission denied），不要用鼠标右键“以管理员身份运行”来解决，除非你清楚自己在做什么。管理员权限的终端会把包写到系统级目录，这可能破坏整个Python环境的权限结构，后面很容易出现不可预期的问题。
正确做法是只给当前用户安装，pip加个--user参数：
bash复制python -m pip install --user jupyter
这样包会装到你的用户目录下，不需要管理员权限，也不影响其他用户。
4. 装完启动失败怎么办：给无法打开和运行代码的问题归个类
安装成功后，下一个集中爆发的问题就是打开失败。启动Jupyter Notebook失败的情况，从现象上归类，其实就几类。
4.1 终端提示找不到命令
输入jupyter之后，报“不是内部或外部命令”或者“command not found”。这类情况基本有两种可能：一是你根本还没安装成功，二是因为pip脚本目录不在PATH环境变量里。
在Windows上用python -m pip install装的包，可执行脚本通常在C:\Users\你的用户名\AppData\Roaming\Python\xx\Scripts目录下，这个目录没加进PATH的话，jupyter命令就找不着。解决办法是打开系统环境变量设置，把该Scripts目录追加到Path里，然后重新打开终端。
另一种做法是不依赖PATH，直接用模块方式启动：
bash复制python -m jupyter notebook
python -m会让Python自己去包安装目录找模块，绕开PATH的问题。如果你不知道系统PATH怎么调，先用这个方式能解决问题，之后再慢慢补环境变量。
4.2 启动了但浏览器没有自动弹出
如果终端提示已经启动，但默认浏览器没打开，先不要关闭终端。那条日志里其实有一个URL，形如http://localhost:8888/?token=xxxx。手动复制这个地址到浏览器访问就行。
浏览器弹不出来通常是系统默认浏览器关联出了问题，或者防火墙拦截了本地端口。如果复制了URL也在浏览器里访问不了，那有可能是8888端口被占用了。这时候可以指定一个新的端口来启动：
bash复制jupyter notebook --port 9999
4.3 浏览器能打开，但“运行”按钮点了没反应
很多新手到了这一步心态会崩：页面上代码写完了，点运行，Cell下方就是不输出结果，也不报错。其实绝大多数情况不是Jupyter坏了，而是代码还在等待执行。
我在调试这类问题时，第一件事是看终端窗口。所有代码执行的结果和错误回显都会同步在启动Jupyter的那个终端里。如果运行一个死循环，终端会卡住状态。如果你不小心把变量名写错，Cell里看不到红色报错，那大概率是Cell左侧的In [*]一直不变成In [数字]。
遇到In [*]卡住，我一般做下面几个操作：
- 点击菜单栏的“Kernel” -> “Interrupt”，尝试中断内核当前正在执行的耗时任务。
- 如果中断没用，选择“Kernel” -> “Restart Kernel”，重启内核。
- 重启后还是不复位，那就是环境层面的问题，去终端看有没有Traceback输出。
4.4 找不到内核（No kernel found）
启动Jupyter之后，页面右上角可能提示找不到内核。这种情况往往是因为你现在全局的Jupyter没找到你另外一个环境里的ipykernel内核，或者ipykernel本身没装好。
处理方式前面2.4节写过，重新为该环境安装ipykernel并手动注册一次就行。如果注册完还是找不到，重点检查一下jupyter kernelspec list的输出，看内核配置文件到底写到了哪个目录。
bash复制jupyter kernelspec list
如果列出来的内核路径在某个不存在的目录里，那多半是旧配置残留，直接用下面的命令移除，再重新注册：
bash复制jupyter kernelspec remove myenv
另外提醒一句，Jupyter Notebook对PyQt或某些Qt相关包的依赖可能导致启动阶段崩溃，如果你装了多个Python环境和一堆包，还是建议在独立环境里跑，避免相互拉扯。
5. 侧边栏显示标题总览和目录到底怎么装
熟悉Notebook之后，你可能会发现一个痛点：文件长了之后，Cell一个接一个，想快速跳到自己关心的章节，得手动往下翻，太费时间。网上大家都在问“侧边如何显示标题总览”和“jupyter notebook目录安装”，其实这个问题在原生Jupyter Notebook里并不那么开箱即用，需要借助扩展。
5.1 先确认你的版本是notebook还是JupyterLab
先说句题外话：现在Jupyter生态里的主力其实是JupyterLab，界面更像IDE，左边自带有文件树和大纲面板，很多体验完胜老版Notebook。但很多教程、课程和内部工具还是基于老版Notebook界面，所以大家的需求依然存在。
如果你用的是老版Jupyter Notebook（界面地址栏显示的是/tree这种路径），想实现目录功能，方案基本锁定在安装jupyter_contrib_nbextensions扩展包。在环境里执行：
bash复制python -m pip install jupyter_contrib_nbextensions
jupyter contrib nbextension install --user
安装完，启动Jupyter Notebook，页面顶部的菜单栏会多一个“Nbextensions”标签。在里面找到“Table of Contents (2)”，勾选启用，然后刷新页面，左侧栏就会出现目录了。
这个扩展除了能显示标题总览，还会在每个Markdown格式的Cell右上角生成一个小的目录按钮，用起来确实方便。如果你的魔法标题用了Markdown的#、##等语法，它会自动收集并分级展示。
5.2 如果nbextensions勾选不生效怎么办
有相当多的人反映：装完扩展也勾选了，但是没看到左侧目录。这种情况我建议按以下顺序排查：
- 确认页面是否刷新过。扩展往往只有在Notebook首次加载时才会注入，旧打开的页面需要刷新。
- 确认你编辑的Cell是Markdown格式，不是Code格式。代码Cell里的注释写得再整齐，也不会被识别成标题。
- 把Notebook里对应的标题Cell重新运行一次，让渲染后的HTML更新，目录才能抓到最新标题。
- 打开浏览器开发者工具（F12），查看Console面板有没有红色报错。如果有JavaScript报错，多半是扩展版本和notebook版本不兼容。
4.1节的方法主要解决“没有扩展”的问题，如果扩展已经装好但界面不展示，还有一个更直接的方案：在地址栏访问Jupyter基础URL，即http://localhost:8888/nbextensions，看那个页面是不是能正常打开。如果能打开但notebook页面里不生效，换个浏览器或清除缓存通常就好了。
5.3 不同环境下的目录管理方式
如果你的Jupyter版本较新，或者你转向了JupyterLab，那其实自带的“Outline”功能就可以直接显示Markdown标题的总览：
- 打开左侧边栏。
- 点击“Table of Contents”小图标（像几行目录列表的那个）或从菜单View -> Show Table of Contents。
- 侧边栏会列出当前文档中所有标题，点击即可跳转。
JupyterLab里不需要额外装插件，这个功能是默认的，只是很多人不知道入口而已。
5.4 扩展失效的另一种解决：直接装toc扩展的仓库
如果你不想装一整套jupyter_contrib_nbextensions，只是想单独用目录组件，也可以拆开只装ipython-contrib中toc相关的部分。不过单独拆文件比较麻烦，实际上两个方案在代码层面是同一套东西，我个人经验是直接用nbextensions，它把多个实用小工具都集成了，除了目录之外，还有代码折叠、自动保存等选项，灵活性高不少。
再补充一个日常使用细节：目录显示始终有一个前提——你的标题必须用Markdown格式标记。如果某个标题级别的文字是你手动加粗设置的，目录不会识别。写完文档之后多按一次Shift+Enter让Cell渲染一遍，目录就会动态更新这一层的结构，及时看到概览效果。
6. 一个我自己常用的“保姆式”检查清单
这段内容你可以当作一份速查表，碰到问题时先从头过一遍，大部分情况5分钟内就能排查完。
- 当前Python环境是否正确。执行
where python或which python确认没有混用到别的版本。 - pip是否为最新。执行
python -m pip install --upgrade pip。 - 是否加了镜像源或超时参数。如果网络不稳定或下载慢，优先把镜像源和
--timeout加上。 - 是否坚持使用系统级Python硬装。如果多次报错，尝试更换到虚拟环境或conda环境。
- 启动是否用了
python -m jupyter notebook。这样能排除PATH问题。 - 浏览器是否能打开本地端口。不能打开时检查端口是否被占用，必要时
--port换端口。 - 运行代码无响应是否因为死循环。执行Interrupt或Restart Kernel，再看终端日志。
- 目录扩展是否在Notebook页面已经勾选并刷新。标题是否用Markdown标题格式。
- 报错信息是否从头看到尾。找到日志里的“Failed”或“Error”的原始行，而不是只看最后两行。
这9条看起来简单，但我解决过的Jupyter相关问题里，至少有七成都是这几条里的某一条踩了坑。把这些养成习惯，光安装部分就能避开很多雷区。
6.1 实际经验：不要迷信“最新版”
很多人用Jupyter遇到奇怪问题，根源都是Python升级到了3.12甚至3.13，而Jupyter生态里某些依赖还没有跟上适配节奏。我在实际开发里，稳定使用的组合是Python 3.10或3.11，配最新的Jupyter Notebook，极少遇到版本兼容问题。
如果你一定要用最新版Python，那也要留好后路，保证手里有旧版本的解释器可以切换，否则掉进依赖泥潭会消耗大量时间。科学计算领域追求稳定优先，功能保持够用就行，别总想着尝鲜。
6.2 实操中形成的好习惯
安装这件事本身有一层防护逻辑，就是随时记录你已经装了哪些包，这样即使环境崩了，也能一键重建。在环境状态正常的时候，执行：
bash复制python -m pip freeze > requirements.txt
后面如果再换新电脑或环境坏了，就用下面这行还原环境：
bash复制python -m pip install -r requirements.txt
如果你用conda，对应的命令是conda env export > environment.yml，还原命令是conda env create -f environment.yml。
另外一个好习惯是启动Notebook时指定一个专门的工作目录。不要在桌面、下载目录等地方直接启动，因为Jupyter会把当前目录作为浏览器里的根路径，到处乱放文件会让后续整理崩溃。
bash复制cd D:\projects\jupyter
python -m jupyter notebook
把项目文件都收拢在一个目录下，既方便备份，也方便在代码里用相对路径读写文件，这个细节对日常使用体验的影响很大。
6.3 回到最初的那个问题：Jupyter Notebook到底值不值得装
每次写这类教程，我都会顺便感叹一句：Jupyter Notebook在数据分析、教学演示、快速原型验证方面依然是无可替代的。它把代码、说明文字、运行结果放在同一个文档里，这种形式特别适合探索式编程。你不需要一开始就把整个程序写出来，而是一个Cell一个Cell试，一边看结果一边调整思路，然后整理成一条清晰的脉络。
虽然现在JupyterLab和VS Code也提供了类似交互界面，但Notebook这门手艺的基础操作还是值得掌握的。跟着安装一遍、用一遍、再排查一遍，回过头你会发现，之后遇到任何Python包的安装问题，思路基本都是相通的。