1. 搞懂Jupyter是什么再动手装会省很多事我见过太多人卡在Jupyter安装这一步不是因为步骤有多难而是从一开始就没弄明白自己装的到底是什么东西。有人以为它是一个编辑器装了之后发现没有代码高亮就骂街有人以为它就是个网页版的Python解释器结果发现它还能跑R、跑Julia、跑十几个别的语言。把概念理顺后面每一步操作你都会觉得理所当然遇到报错也知道该往哪个方向排查。1.1 Notebook不是编辑器它是一本可以执行的实验记录本我用一个最贴近日常的类比来解释Jupyter Notebook就是一本会算数的实验记录本。普通记事本你写公式它不会算但是在Jupyter里你写下一个单元格按下运行它立刻把结果打印在下面而且这个结果会一直留在页面上。你可以往上翻看到自己十分钟前跑了什么、得到了什么也可以改一行参数重新跑直接对比前后差异。这种代码块即时输出可留存的结构决定了它天然适合做几类事情数据分析探索、机器学习模型调参、教学演示、临时代码验证、把操作过程整理成可复现的报告。它不太适合写大型工程项目那种场景还是交给正经的IDE更稳妥。名字里的Jupyter其实是Julia、Python、R三个词的拼接因为最早它主要服务这三种语言。现在通过内核Kernel机制它可以接入几十种语言的执行引擎你在同一个界面里切换内核就能用不同语言写代码。这个内核概念很重要后面排查单元格执行没反应的故障时核心就是看内核有没有连上、有没有挂掉。1.2 三种安装路径的取舍先想清楚你属于哪一类装Jupyter的路子不止一条不同身份的人选错了会平白多花一两个小时。我把它归纳成三种你对照自己的情况挑安装方式适合人群优点代价Anaconda发行版数据科学新手、要一次性配齐numpy/pandas等库图形化安装装完自带Jupyter和大量库安装包大动辄三四个G装完占空间明显pip安装已有Python环境、想保持环境干净轻量只装需要的版本可控需要自己装一些常用库前期命令行操作多一点Docker镜像熟悉容器、要环境隔离或部署到服务器环境一次配好可复现不污染本机需要先有Docker基础学习成本在容器那部分如果你只是想在本地学Python、跑跑数据分析又不想折腾环境Anaconda是省心的选择但如果你本机已经有Python、平时也习惯用命令行我建议走pip这条路装出来的环境清爽出问题也好定位。至于Docker等你有同一份代码要在几台机器上跑出一样结果的需求时再考虑那不是这篇要展开的重点。顺带说一句版本的事Jupyter Notebook这套东西在2023年前后经历了一次大重构老版本叫notebook6.x新版本基于Jupyter Server重写7.x配置项名字也跟着变了。网上很多教程还停留在6.x时代照着做会发现配置文件里的字段对不上这个坑我在第三章会专门讲。2. Windows下用pip装Jupyter的完整流程这一章我按pip路线走一遍因为Anaconda那种下一步下一步的图形安装没什么可讲的而pip路上的每个细节都值得说清楚。全程我假设你用的是一台干净的Windows 10或11从没装过Python。2.1 Python解释器先落地勾选PATH这个框千万别漏去python.org的下载页拿最新的稳定版安装包。双击运行之后安装界面最底下有两个复选框其中一个写着Add Python to PATH把Python加入环境变量这个框必须勾上。我见过至少五个人在这里栽跟头没勾装完之后Cmd里敲python提示不是内部或外部命令然后开始怀疑人生。为什么这个框这么关键因为PATH是操作系统找程序的一张清单你敲python这个命令时系统会挨个去清单里的目录找有没有叫python的可执行文件。不勾选安装目录就没进清单系统自然找不到。手动补PATH当然也行但那个界面又长又容易点错不如安装时一步到位。装完后马上验证新开一个命令提示符必须新开旧窗口读的是旧环境变量输入python --version pip --version两条都正常返回版本号说明解释器和包管理器都在岗。如果python能出结果但pip报错那多半是安装时没装pip重新运行安装包选Modify补上即可。2.2 换国内镜像再装Jupyter速度能差出十几倍直连官方源装包在国内网络环境下经常会卡在某个包上几十秒甚至超时。先把默认源换成国内镜像这一步一次设置长期生效收益极高pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple设置完可以用pip config list确认一下。然后在命令提示符里执行安装pip install notebook如果你更想用新一代的Lab界面那一并装上pip install jupyterlab这里有个容易混淆的点pip install jupyter和pip install notebook不是一回事。jupyter是一个总包会把Notebook、Lab、nbconvert、jupyter-console等一大堆组件全拉下来体积更大而notebook只装网页版Notebook本体。除非你确定要用到全套工具否则只装需要的那个环境更干净升级时也少牵扯。提示如果你的机器上有多个Python版本装包前先确认pip对应的是哪个解释器。用pip -V能看到它关联的Python路径。装到了A解释器上却用B解释器跑Jupyter症状就是明明装了却提示找不到模块这个坑非常隐蔽。2.3 首次启动、工作目录与端口设置装完之后在命令提示符里敲jupyter notebook正常情况下终端会刷出一串日志最后给出一个带token的地址形如http://localhost:8888/tree?token一长串字符浏览器自动弹出Notebook的文件列表页面。这就跑起来了。第一次用我强烈建议先做两件事都是为了让后续使用更顺第一件是生成配置文件。默认情况下Jupyter的工作目录是你启动命令时所在的目录如果你在C盘用户目录下敲的命令它就在那里新建文件用着用着文件散得到处都是。执行jupyter notebook --generate-config它会在你的用户目录下生成一个jupyter_notebook_config.py文件。打开它找到与工作目录相关的配置项把默认目录改成你专门放代码的文件夹。注意版本差异新版本7.x里字段是c.ServerApp.notebook_dir老版本6.x里是c.NotebookApp.notebook_dir改错了不生效。改的时候记得把行首的注释符号去掉路径里的反斜杠要用双写或者改成正斜杠。第二件是固定端口或不自动开浏览器。如果你本机8888端口被别的程序占用了启动会提示连不上可以用jupyter notebook --port 8889临时换端口想永久改就在配置文件里找到端口字段修改。如果你习惯用固定的浏览器比如自己配置好插件的那个不希望它每次自动弹一个默认浏览器把c.ServerApp.open_browser老版本c.NotebookApp.open_browser设成False之后手动打开终端里给出的地址就行。这两项配置看起来不起眼但它决定了你后面几个月用起来是顺手还是别扭值得在第一次安装时多花五分钟。3. 装完打不开、浏览器不弹、单元格没反应故障排查实录这部分是我觉得最该写的内容因为网上大多数教程只教你顺利的情况下怎么装而真实世界里十有八九会碰到意外。下面这几个故障我都亲自遇到过每次都是靠一步步缩小范围定位的我把排查链路完整写出来你照着走就行。3.1 命令跑完了浏览器就是不弹窗症状是终端日志正常也给出了http://localhost:8888/...的地址但浏览器没有任何反应桌面静悄悄。排查第一步先别管弹不弹窗手动把终端里的完整地址复制到浏览器地址栏。如果能打开说明Jupyter服务本身完全正常问题只出在自动唤起浏览器这个环节。这通常是因为系统默认浏览器设置异常或者Jupyter调用的启动方式被拦截了。第二步检查是不是端口被占用导致服务其实没起来。看终端日志里有没有Port 8888 is already in use之类的字样有的话换端口重开。第三步如果手动开也打不开看看终端是不是已经退出了。有时候日志刷完最后一行是报错信息窗口一闪或者滚上去了你没注意。往上翻日志找带Error或Traceback的行那才是真正的病根。处理方案上我一般直接关掉自动开浏览器上文提到的open_browserFalse自己手动开省得每次都要等它折腾。这个习惯建立起来之后反而很少再被这个问题烦到。3.2 启动时的DLL加载报错别急着重装整个Python有一类报错长这样ImportError: DLL load failed while importing rpds。第一次见的人容易慌以为Python装坏了要全部重来其实不用。这个报错的本质是某个依赖包这里是rpds它底层是Rust编译的在加载时找不到对应的动态链接库通常发生在以下几种情况Windows上缺少Visual C运行库、这个包的预编译轮子wheel和你的Python版本或系统架构不匹配、又或者是升级过程中装了个半成品。排查和修复的顺序我建议这样先单独重装这个报错点名的包pip install --force-reinstall rpds-py。很多情况下是安装不完整强制重装就好。如果重装后还报同样的错检查你的Python是不是64位、以及是不是比较新的版本比如3.12、3.13。有些包的新版本对Python版本支持有延迟可以尝试退到上一个稳定小版本。再不行就检查系统是否缺Visual C Redistributable去微软官网装最新的运行库再试。注意遇到这类报错最忌讳的动作是把Python卸了重装。因为报错本身指向的是某个具体依赖重装整个解释器不仅费时间还可能把已经配好的其他环境一起搞乱。先精确定位到是哪个包、哪个库出的问题再针对性处理。3.3 单元格敲进去回车没反应或一直显示星号这个症状描述起来就是代码写完了按运行方括号里的数字变成[*]然后就一直转不出结果也不报错。先分辨两种情况。一种是代码本身在长时间运行比如读了个大文件、跑了个耗时循环那它就是在跑等着就好。另一种是内核卡死或断开这时候无论等多久都不会有结果。判断方法很简单看界面右上角的内核状态指示器。如果显示的是未连接或者一个空心圆说明内核已经断了得重启内核菜单里找Restart Kernel。重启之后之前定义的变量会全部丢失需要重新运行前面的单元格。内核断开的常见原因有几个代码里写了死循环把内存吃满、调用了会导致解释器崩溃的原生库、或者浏览器标签页挂起太久导致前后端通信中断。我的经验是写循环时养成设个中断条件的习惯处理大内存数据时留意任务管理器里的占用能躲掉大部分内核崩溃。还有一个特别隐蔽的情况你在终端启动Jupyter的那个窗口被关掉了。命令行窗口是Jupyter服务的宿主进程窗口一关服务就没了浏览器里看着界面还在其实后端早断了任何操作都石沉大海。所以启动Jupyter的那个终端窗口别关这是很多新手完全没意识到的细节。4. 单元格操作、快捷键与代码补全把效率真正拉起来装好能跑只是及格线用好用顺才是这篇博文想给你的东西。Jupyter的效率提升八成集中在快捷键和几个扩展功能上下面逐个说。4.1 命令模式和编辑模式两种状态的快捷键完全不同Jupyter的单元格有两种状态理解这一点是掌握快捷键的前提。编辑模式光标在单元格里闪烁你可以打字改代码。按Enter进入这个模式。命令模式单元格边框变成蓝色光标不在里面此时的按键是对单元格本身操作而不是往里面打字。按Esc进入这个模式。新手最容易困惑的就是为什么我按了删除键没删掉代码反而把整个单元格删了答案就是你处在命令模式那些字母键被当成了快捷键。常用快捷键整理如下按价值排序快捷键所在模式作用Shift Enter两种都行运行当前单元格并跳到下一个Ctrl Enter两种都行运行当前单元格但不跳转Alt Enter两种都行运行当前单元格并在下方插入新单元格A命令模式在上方插入新单元格B命令模式在下方插入新单元格DD命令模式删除当前单元格M命令模式把当前单元格切换成MarkdownY命令模式把当前单元格切换回代码Ctrl /编辑模式注释或取消注释选中行其中Shift Enter和Ctrl Enter的区别值得记牢调试一段代码时反复运行同一个单元格用Ctrl Enter更稳因为它不会把你的视图跳走而顺着流程往下跑时Shift Enter更顺。我调模型参数的时候几乎全靠Ctrl Enter改一下参数按一下结果就在眼皮底下变。4.2 代码自动补全怎么开两种方案各有取舍默认状态下Notebook的补全能力比较弱新版其实已经内置了基于语言服务的基本补全。如果你想要更接近IDE那种输入几个字母就弹出候选列表的体验可以考虑装扩展。方案一走经典扩展包这条路适合还在用老版Notebook的人pip install jupyter_contrib_nbextensions jupyter contrib nbextension install装完之后重启Notebook界面上会多出一个Nbextensions标签页里面有一堆可勾选的扩展。补全相关的、以及生成目录的扩展都在这个列表里勾上即可生效。这套扩展胜在功能多、界面化操作但它是围绕老版Notebook设计的新版里可能不兼容。方案二走**语言服务协议LSP**这条路配合JupyterLab使用效果最好pip install jupyter-lsp jupyterlab-lsp这套方案的好处是补全、跳转、悬停提示都比较接近现代编辑器代价是配置稍复杂且更适合Lab界面而非经典Notebook。我的建议是如果你刚入门先用新版本自带的补全输入时按Tab能补就够用不要一上来就装一堆扩展环境越复杂越容易出问题。等用了一段时间觉得补全确实不够再去折腾扩展那时候你对环境也更熟悉出问题能自己处理。4.3 Markdown单元格与自动目录让Notebook能当报告用Jupyter真正的价值不只是跑代码而是能把代码、运行结果、文字说明三样东西混在一起形成一份可以往下讲述的文档。这一点靠Markdown单元格实现。把单元格切到Markdown模式命令模式下按M你就可以在里面写标题、列表、加粗、表格、公式运行之后它会渲染成排版好的文字。我习惯的写法是每个分析主题先用一个Markdown标题开场说明背景下面跟代码单元格和结果中间穿插Markdown解释结果意味着什么。这样一份Notebook交给别人对方不用问你任何问题就能读懂来龙去脉。当Markdown标题多起来之后目录就成了刚需。老版Notebook可以通过前面提到的扩展包里的目录工具实现激活后侧边栏会实时列出所有标题点击就能跳转。新版的Lab则在左侧栏自带大纲功能不需要额外装东西。写长文档时这个目录能帮你快速定位也方便导出后给别人看。导出方面在菜单里选Download as可以把Notebook转成HTML、Markdown、PDF等格式。命令行下也能批量处理jupyter nbconvert --to html 你的文件.ipynb转成HTML之后发给不装Python的同事对方用浏览器就能看到完整的代码和结果这在汇报场景里特别实用。5. Jupyter Lab和经典Notebook到底该用哪个这是我被问得最多的一个问题答案是看场景但我想把差异讲具体你才能自己判断。简单说经典Notebook是单文档界面一次主要面对一个文件Jupyter Lab是IDE式的工作台可以多标签、拖拽布局、侧边栏管理文件。我把关键差异列一下维度经典NotebookJupyter Lab界面形态单页面一个文件一个标签多面板工作区可拖拽分屏文件管理独立的文件列表页左侧常驻文件树插件生态以经典扩展为主以Lab扩展为主方向更主流上手难度极低打开就会用稍高功能多需要熟悉长期趋势维护模式官方主推方向我的实际体验是如果只是临时跑几行代码、做个小分析经典Notebook足够启动快、界面简单、没有干扰。如果要同时看多个文件、要边写文档边跑代码、要长时间泡在里面工作Lab明显更舒服。两者可以同时装在一台机器上jupyter notebook和jupyter lab两条命令分别启动想用哪个用哪个互不影响。有个小细节提一下Lab的启动命令和Notebook共用一个底层服务端口默认都是8888。如果你先开了Notebook又去开Lab会提示端口占用这时候给其中一个加个--port参数换端口就行。或者干脆先关掉一个再开另一个。6. 用久了才会攒下来的几个经验写到这儿安装和主要用法都覆盖了最后分享几点是我自己用了几年之后才慢慢意识到的算不上教程但对长期使用挺有用。第一点给每个项目建独立的工作目录而不是所有文件堆在一个文件夹。Jupyter默认从启动目录开始列文件如果你所有Notebook都在一个目录里过几个月就会变成一个巨大的混沌文件夹。我的做法是按项目建文件夹每个文件夹里放对应的Notebook和数据集启动时用命令行切到对应目录再开或者直接在配置文件里指向一个总目录再在里面分层。第二点内核选择要留意。如果你装了虚拟环境启动Notebook之前在命令行里先激活那个环境这样Jupyter用的就是该环境的内核。不激活直接开很容易出现我明明在这个环境里装了某个库Notebook里却说没有的情况。想要更规范地管理可以给每个虚拟环境注册独立内核让Notebook里能直接切换这个操作搜一下注册ipykernel就有详细步骤。第三点定期清理和更新。包装多了之后环境会越来越臃肿偶尔会遇到版本冲突。我一般每隔一段时间用pip list --outdated看看有哪些包可以升级重要项目用的环境则冻结一份依赖清单pip freeze requirements.txt备用出问题时能快速回滚。第四点格式化代码别忘了。Notebook里代码写乱了很难看可以在单元格开头加%load_ext加载格式化工具或者干脆在提交前用命令行统一格式化.ipynb文件让导出的报告看起来更专业。这些东西没有一样是必须的但它们决定了你用Jupyter是能用还是好用。装完之后真正的功夫都在这些日常习惯里。