这两年我从 Jupyter Notebook 切到 JupyterLab 之后最直接的感受就是我不用再同时开着五六个浏览器标签页来回找了。很多人第一次听说 JupyterLab都觉得它只是换了层皮的 Notebook实际上它是 Jupyter 生态里的新一代交互界面把文件管理、代码编辑、终端、数据查看这些东西全部收进了一个工作台里。对还在靠 Jupyter Notebook 写数据分析和教学演示的人来说把它当成日常主力工具完全够用而且迁移成本低到可以忽略——.ipynb文件直接打开就能用。这篇内容我会从安装路线开始讲覆盖 pip 和 Miniconda 两种方式、启动细节、界面功能、扩展配置最后把我实际用下来踩过的几个坑一并交代清楚。1. 从 Notebook 到 JupyterLab先搞清楚它到底“重”在哪、“轻”在哪1.1 最直观的区别一个页面是一个文档一个页面是一个工作台经典 Jupyter Notebook 的逻辑是“一个浏览器标签页 一个.ipynb文件”。我当年做一个小项目常常要同时打开数据清洗、特征工程、可视化三个 notebook结果就是标签页开了一排每个页面的菜单栏、工具栏、logo 全是重复的内存占用也跟着涨。JupyterLab 则完全不同。你启动之后看到的是一个类似 IDE 的单页应用SPA左侧是文件浏览器中间是编辑区右侧可以打开属性面板。你可以把两个 notebook 拖到同一屏幕左右分屏也可以一边开 notebook 一边在旁边的终端里跑 shell 命令不需要另外开窗口。它的定位不是“更好看的 Notebook”而是“一个能装下 Notebook 的工作台”。我第一次打开 JupyterLab 时的反应是“这也太空了”因为经典 Notebook 打开就是一个空白 cell而 JupyterLab 打开的是一个 Launcher 起始页上面有 Notebook、Python 文件、终端、控制台等入口。这个差异非常关键Notebook 默认只让你写 notebook而 JupyterLab 默认让你干很多种活。1.2 标题里说的“轻量替代”轻的不是体积很多人在评论区争论过JupyterLab 明明比 Notebook 多装了很多前端资源内存占用也更高凭什么叫“轻量替代”我自己的理解是标题里的“轻量”指的是使用体验上的轻不是资源占用上的轻。文件操作轻不需要为了打开一个.py文件或者查看 CSV 再去装别的编辑器文件浏览器里直接双击就能看。工作流切换轻从写代码到跑命令到看结果全部在一个窗口内完成不必跳来跳去。管理成本轻 Notebook 时代的jupyter notebook和ipython是不同命令JupyterLab 出来以后统一由 Jupyter Server 管理你只需要学 jupyter 这一条命令体系。反过来说如果你追求的是极致的启动速度和最低内存占用比如在只有 1G 内存的云服务器上跑那 JupyterLab 反而不如经典 Notebook 或者纯 IPython console。所以我的建议是本地开发、日常数据分析、教学演示用 JupyterLab服务器上临时开个交互环境可以继续用保守方案。1.3 它适合谁不适合谁我观察自己部门的同事觉得有三类人最适合从 Notebook 切到 JupyterLab写数据分析脚本的人每天跟 DataFrame、matplotlib 打交道需要在同一个工作区里来回调试。做课程演示或写教程的人JupyterLab 能把 Markdown、代码、图表和终端整合在一个窗口里演示的时候不容易手忙脚乱。觉得 VSCode 太重、只想开个浏览器就开始写的人JupyterLab 不需要配调试器和插件市场默认环境已经够用。不太适合的人是以大型软件工程为主、需要重度重构和复杂调试的开发者以及只是想随便记点笔记、不想碰代码的人。前者更适合 VSCode 或 PyCharm后者用普通 Markdown 编辑器就好。工具没有高低之分只有匹配度问题。2. 安装路线pip 和 Miniconda 到底怎么选2.1 装之前先确认你在哪个 Python 环境里很多人安装时出的问题根源根本不是 Jupyter 本身而是连自己用的是哪个 Python 都没搞清。Windows 上如果你装过 Anaconda又装过 Python.org 的官方包再叠一个 VS Code 自动装的 Python系统里通常会有好几个解释器。所以安装前先花一分钟确认环境# Windows 用 wheremacOS / Linux 用 which where python where pip # 查看版本和路径 python --version pip --version如果你用 Miniconda就先进对应的命令行工具Windows 上叫“Miniconda Prompt”或“Anaconda Prompt”再执行上面的命令。你会发现这里面的 python 路径指向你的 Miniconda 安装目录这很重要——之后所有包都要装到这个环境里别装到系统自带的另一个 Python 里去了否则会出现“装好了却启动不了”的诡异情况。2.2 最快跑通pip 安装 JupyterLab在没有 Conda 的机器上pip 是最快的路径pip install jupyterlab装完以后直接启动jupyter lab第一次启动会自动在浏览器打开http://localhost:8888/lab。如果没自动打开就把命令行里打印的 URL 手动复制到浏览器。这里有一个容易被老教程误导的点很多人以为装了 JupyterLab 之后jupyter notebook命令应该还能用。实际上新版 JupyterLab 是独立于经典 Notebook 包的如果你只装了jupyterlab运行jupyter notebook有可能提示找不到子命令。想继续用经典 Notebook 界面需要额外安装pip install notebook也就是说现在 Jupyter 生态里有两套界面内核和文件格式是共享的但前端是分开的。2.3 Miniconda 安装解决“装完不知道用哪个”的问题热词里有一条“miniconda安装后 如何使用jupyter notebook”这个我太有感触了因为这几乎是每个 Miniconda 新手都会碰到的事装完了 Miniconda开始菜单里有“Jupyter Notebook”快捷方式但点下去不是闪退就是报“找不到指定的程序”。原因通常是Miniconda 默认环境base里根本没装 notebook 或 jupyterlab开始菜单的快捷方式只是安装时帮你生成的脚本真正要跑起来得先安装对应包。正确的操作是这样# 先创建一个独立环境推荐别把包全都堆在 base conda create -n py311 python3.11 -y conda activate py311 # 再用 conda 安装 JupyterLab conda install -c conda-forge jupyterlab -y这样你的 py311 环境里就有了 JupyterLab。以后每次使用先执行conda activate py311再执行jupyter lab。如果你实在不想建环境直接装到 base 里也行conda install -c conda-forge jupyterlab -y但我真的不建议这么做。因为做数据分析的人往往会有多个项目每个项目依赖不同的包版本全都堆在 base 里早晚会冲突。用虚环境把 JupyterLab 装在项目环境里或者只在 base 装一个通用的 JupyterLab再通过内核机制引入其他环境这才是干净的做法。这个后面会专门讲。2.4 pip 和 conda 混装时的一个原则你如果用了 Miniconda我建议能conda install的优先用 conda实在 conda 上没有的包再用 pip。原因是 pip 和 conda 两套包管理器对文件的管理方式不同混装顺序不对可能互相覆盖。万一你在 conda 环境里已经用 pip 装了一半也不要慌JupyterLab 这种纯 Python 包通常不会出大问题真出问题就重装一遍pip uninstall jupyterlab -y conda install -c conda-forge jupyterlab -y3. 启动细节从命令行到浏览器还有那个“找不到指定的程序”3.1 jupyter lab 启动命令的常用参数最基本的启动就一条命令jupyter lab。但实际使用中下面这几个参数用的频率非常高# 指定其他端口适合 8888 被占用的情况 jupyter lab --port8889 # 启动时不自动打开浏览器适合在远程服务器上运行 jupyter lab --no-browser --port8888 # 指定工作目录打开后文件浏览器默认定位到该目录 jupyter lab --notebook-dirD:\projects\data # 允许所有 IP 访问谨慎使用通常搭配 token 认证 jupyter lab --ip0.0.0.0 --port8888这里我要强调--notebook-dir。很多人都是从桌面快捷方式直接点进 JupyterLab 的结果发现文件浏览器里显示的永远是某个固定目录找不到自己放代码的文件夹。你可以在启动命令里加上这个参数或者改配置文件后面讲不要傻乎乎地每次在文件浏览器里点半天目录层级。3.2 浏览器打不开时的处理思路JupyterLab 启动后终端里会打印一串 URL类似http://localhost:8888/lab?tokenxxxxxxxxxxxxxxxxxxxx如果浏览器没有自动打开原因无非三种浏览器阻止了自动弹出——手动复制 URL。你在远程服务器上——不能直接用 localhost要改成服务器的 IP。端口错误——--port8889会改变端口号但你还在尝试 8888。远程访问时一定要把 token 带上。token 就相当于你的访问凭证丢了的话可以从终端里翻也可以在配置里取消或重设。3.3 “Jupyter Notebook 启动时显示找不到指定的程序”排查链路这个报错在 Windows 上极其常见尤其是用 Miniconda 或 Anaconda 的用户。我在帮同事处理时见过五种不同原因完整的排查链路如下第一步分清报错出现的场景如果是点击开始菜单的“Jupyter Notebook”快捷方式报错多半是环境里没装对应包或者快捷方式指向的路径已经变了。如果在命令行里运行jupyter notebook报错才是真正的可执行文件或依赖问题。第二步命令行里验证 jupyter 是否可用jupyter --version如果提示“不是内部或外部命令”说明 Scripts 目录不在 PATH 里。Miniconda 用户出了这个问题可以在 Miniconda Prompt 里执行conda activate base conda install notebook jupyterlab -y第三步用绝对路径或 python -m 方式绕过 PATH 问题# 找到你的 python 路径后直接用模块方式启动 python -m jupyter lab python -m jupyter notebookpython -m的方式不依赖jupyter-notebook.exe是否在 PATH 中可以绕过很多快捷方式层面的问题。第四步检查环境是否错乱有些机器上装了多个 Python 版本Quick Launch 里的快捷方式指向的是某个已经被卸载的 Python 目录所以会报“找不到指定的程序”。打开快捷方式的属性看看“目标”一栏指向哪个路径如果路径不存在删除快捷方式重新在命令行里启动即可。第五步重装一次解决依赖残留pip uninstall jupyter jupyterlab notebook -y conda install -c conda-forge jupyterlab -y我见过一个案例用户之前从官网 Python 3.7 跑到 Miniconda 3.11系统里残留了一堆旧 jupyter 脚本重装一次立刻就好。第六步看看杀毒软件有没有拦截这一条属于玄学但真实发生Windows Defender 或第三方杀毒软件可能拦截 python.exe 或 jupyter 脚本生成临时文件。如果你重装后依然报错尝试把 Python 安装目录加入白名单再启动一次。4. 上手 JupyterLab界面布局和真正提升效率的日常操作4.1 工作台布局左侧文件浏览器和中间的 Launcher启动后默认界面左侧是文件浏览器中间是 Launcher 起始页。文件浏览器里能直接预览图片、CSV、JSON 等常见格式右键可以新建 folder、notebook、Python 文件、Markdown 文件也可以打开终端。这个设计比经典 Notebook 好了太多——你不需要先启动一个 notebook 才能写代码你可以先建.py文件跑通了再决定要不要转成 notebook。Launcher 里的几个入口值得留意Notebook新建.ipynb文件。Python File新建普通.py文件适合写正式脚本。Markdown File不只是 Notebook 里的 Markdown 单元格而是独立的.md文档。Terminal在浏览器里打开一个 shell 终端。Console打开一个 Python 控制台适合快速验证小段代码。我第一次用的时候最喜欢的是 Terminal因为以前用 Notebook 时想查个文件路径都要切到外部终端现在直接在同窗口里操作。4.2 多标签与拖拽分屏真正拉开差距的地方JupyterLab 允许你把任意标签页拖拽到工作区的任意区域形成上下或左右分屏。比如我在左边开一个数据处理的 notebook在右上角开一个 Markdown 文档用来记录想法在右下角再开一个 CSV 预览文件。三个区域互不干扰动任何一个都不会抢占焦点。这个功能在经典 Notebook 里是做不到的你只能用浏览器多窗口勉强模拟。对我这种习惯边写代码边对着数据文件核对逻辑的人来说拖拽分屏是最实用的一项。另一个很实用的小操作是Shift 左键点击第二个文件会将文件在右侧分屏打开不用手动拖拽适合快速对比两个 notebook。4.3 命令面板和快捷键是效率的核心经典 Notebook 时代大家记住的快捷键大多是单元格操作那套A 在上方插入、B 在下方插入、M 转 Markdown、Y 转 Code。JupyterLab 保留了这些而且多了一个“命令面板”。打开命令面板的默认快捷键是CtrlShiftCmacOS 是CmdShiftC也可以用菜单 View 里的 Activate Command Palette 打开。如果跟你系统快捷键冲突可以在设置里改。面板里几乎所有功能都能搜索新建、保存、关闭、切换布局、安装扩展、打开终端……我实际使用后最常用的搜索词反而是“Close”和“Split”因为鼠标点菜单太慢。下面是我平时会背下来的快捷键配合非常快操作快捷键运行当前单元格并移到下一格ShiftEnter运行当前单元格不动位置CtrlEnter运行当前并向下插入新格AltEnter执行代码补全Tab查看函数文档/签名ShiftTab切换命令模式/编辑模式Esc / Enter在上方插入单元格A在下方插入单元格B删除当前单元格连按两次 D单元格转 MarkdownM单元格转代码Y打开命令面板CtrlShiftC隐藏/显示左侧栏CtrlB注意删除单元格的 DD 是在命令模式下按的。如果你在编辑状态要先按 Esc 退出编辑再快速按两下 D否则会变成往单元格里敲字母。4.4 单元格执行状态和右侧属性面板在 Notebook 里运行代码时左侧会显示In [1]、In [2]这种序号正在运行的单元格会变成In [*]。这个逻辑和经典 Notebook 一样。JupyterLab 3.0 之后还在右侧加了属性面板可以查看当前选中单元格的类型、执行次数以及 notebook 的基础元信息。对于做教学的人来说这个面板可以方便你统一调整多个单元格的样式和运行配置不过平时用到的频率不算高。我更想提醒的是如果你在 JupyterLab 里打开了一个旧版内核生成的 notebook执行计数可能对不上这是正常现象不是 bug。内核执行计数是从当前会话开始计算的notebook 文件里记录的历史计数只是一个展示信息不对齐也无所谓。4.5 终端和中文用户需要注意的编码如果你在 Windows 上的 JupyterLab 终端里跑命令遇到中文乱码先检查时代码文件或命令行是不是 GBK 编码和 UTF-8 混了。在终端里执行chcp 65001切到 UTF-8 代码页能解决大部分中文显示问题。这个问题跟 JupyterLab 本身关系不大但第一次在浏览器终端里看到乱码时很懵所以写出来让大家少走弯路。5. 配置文件和扩展推荐让 JupyterLab 更顺手又不把它搞臃肿5.1 配置文件在哪怎么改JupyterLab 的配置是通过一个 Python 文件控制的可以用命令生成jupyter lab --generate-configWindows 下生成的文件在C:\Users\你的用户名\.jupyter\jupyter_lab_config.pymacOS / Linux 一般在~/.jupyter/jupyter_lab_config.py。打开这个文件常见的修改项如下# 端口 c.ServerApp.port 8888 # 自动打开浏览器 c.ServerApp.open_browser False # 默认工作目录 c.ServerApp.root_dir D:/projects # 设置空 token仅限本机使用远程别这么干 c.ServerApp.token 这里提醒一下老教程里动不动就让你改c.NotebookApp.token 那是经典 Notebook 时代的配置。新版 JupyterLab 是c.ServerApp两套配置项不完全互通。你如果在网上搜索时看到了c.NotebookApp先确认版本不要直接复制粘贴到jupyter_lab_config.py里否则不会生效。5.2 我常用的几个扩展装了不后悔卸载也不心疼JupyterLab 3.0 以后大部分扩展都能直接用pip安装不用再执行jupyter labextension install省了很多事。这里是我实测过、觉得值得装的一组# 图形化 Git 操作 pip install jupyterlab-git # 代码补全和诊断配合 python-lsp-server pip install jupyterlab-lsp pip install python-lsp-server # 显示每个单元格运行时间 pip install jupyterlab-execute-time # 支持直接画 drawio 流程图 pip install jupyterlab-drawio装完重启 JupyterLab 就能看到对应功能。jupyterlab-git会在左侧栏多出一个 Git 面板能看到文件变更、提交记录支持一键 commit/push。对于不想切到命令行的朋友很友好。jupyterlab-lsp是补全和跳转的关键。Python 用户配合python-lsp-server在 notebook 里写代码时补全提示更智能还能跳转到函数定义。jupyterlab-execute-time会在单元格下面显示耗时比如2.3s。我分析慢查询时全靠它定位瓶颈。jupyterlab-drawio不是数据分析必需但画流程图、脑图很好用。5.3 内核管理让所有 conda 环境都出现在 JupyterLab 里有一个非常常见的需求JupyterLab 装在 base 环境但我想用另一个 conda 环境 py311 里装的 pandas 版本。处理方法不是重新把 JupyterLab 装进每个环境而是给目标环境安装 ipykernel 并注册到 Jupyter 里# 先激活目标环境 conda activate py311 # 安装 ipykernel conda install ipykernel -y # 注册内核--display-name 是你在 JupyterLab 里看到的名字 python -m ipykernel install --user --namepy311 --display-name Python 3.11 (py311)以后新建 notebook 时内核选择列表里就会有“Python 3.11 (py311)”。这样 JupyterLab 只需要有一个通向所有环境的入口却可以很多个。5.4 别让扩展变成新的负担我曾经一口气装了七八个花里胡哨的扩展结果 JupyterLab 启动从几秒变成十几秒浏览器来回切面板还会卡。后来清理掉一半只留下 git、lsp、execute-time 这几个真正会用的。大家清理扩展时可以这样操作pip list | grep jupyterlab看到不常用的直接pip uninstall 包名。JupyterLab 的美妙恰恰在于它可以按需加装但“按需”这两个字是关键——装一堆用不上的就把“轻量”这个优势亲手丢掉了。6. 从 Notebook 迁移到 JupyterLab我实际踩过的几个坑6.1 ipynb 文件迁移其实不用迁移jupyter notebook保存的.ipynb文件和 JupyterLab 保存的.ipynb是同一个格式底层是 JSONJupyterLab 打开后直接进入新版界面不需要转换或导出。这一点对老用户来说是最舒服的你积累了一堆 notebook切换工具后照样打开。但有一点要注意如果你在经典 Notebook 里用了某些老版本的 nbconvert 魔法或自定义 JS 扩展迁移到 JupyterLab 后这些前端层面的东西大概率不兼容。我早年写过一个把单元格输出导出成特殊 HTML 的扩展切到 Lab 后就不生效了。解决办法是换个原生实现不要再依赖旧 Notebook 页面的注入脚本。6.2 双击 .ipynb 文件打不开或者打开了是旧 NotebookWindows 用户安装过 Anaconda、又装过 VS Code 之后系统里可能有多个程序抢着关联.ipynb文件。双击后经常直接打开 VSCode或者打开的是经典 Notebook 而不是 JupyterLab。我的做法是不要依赖双击打开文件先启动 JupyterLab再用左侧文件浏览器定位文件。这个几乎没有成本也能保证每次打开的都是 Lab 界面。如果你实在想双击就进 Lab可以在系统“默认应用”里把.ipynb关联到 JupyterLab 的可执行文件但不同版本路径差异大说实话不划算。6.3 内核一直显示 Connecting to Kernel换了 conda 环境后notebook 连不上内核是最容易遇到的。通常表现为单元格区域上方一直转圈写着 “Connecting to Kernel”。排查思路按顺序来确认内核名称是否存在于 Jupyter 内核列表里jupyter kernelspec list。如果不存在重新注册目标环境的内核看 5.3 节。如果存在但连不上多半是 ipykernel 版本和内核环境不匹配重新安装conda activate py311 conda install ipykernel --force-reinstall -y还有一种是旧内核缓存导致的。JupyterLab 设置面板里可以选择“重置内核”。重置之后问题基本都能解决。6.4 每次打开都在家目录想去项目目录怎么办如果你嫌每次启动后都要在文件浏览器里一层层点进去直接把启动命令改成jupyter lab --notebook-dirD:\projects\my_projectWindows 用户还可以做一个批处理文件放在桌面内容就是这一行命令双击即用它启动。比修改开始菜单快捷方式更可控。6.5 配置不生效改了半天没反应修改jupyter_lab_config.py后必须完全重启 JupyterLab 才生效。很多人改完配置直接刷新浏览器发现没用就是因为后台的 Jupyter Server 还跑着旧配置。重启时可以顺手把占用端口的旧进程杀掉# Windows 上查看 8888 端口占用 netstat -ano | findstr :8888 taskkill /PID 你的进程号 /F # macOS / Linux 上 lsof -i :8888 kill -9 进程号6.6 扩展装完看不到入口装了 jupyterlab-git 但左侧栏没出现 Git 面板多数是扩展没有安装到正确环境。JupyterLab 3.0 之后扩展与前端捆绑安装位置必须和 JupyterLab 本身在同一个 Python 环境。用pip list | grep jupyterlab-git确认扩展所在环境再确认 JupyterLab 启动也是这个环境。如果实在找不到入口去命令面板搜“Git”通常在“Settings 或 View”里能找到切换。或者重启一次浏览器端前端资源加载没刷新也会出现不显示的情况。我自己从 Notebook 切换过来后大概用了两周才彻底摆脱下意识开多个浏览器标签页的习惯。现在回头看JupyterLab 最值得称赞的一点是它没弄出另一套难学的交互方式而是把 Notebook 里已有的操作习惯原样保留同时在文件管理、终端、多面板这些环节补齐了我长期抱怨的短板。如果你手头已经有一堆.ipynb文件又受够了在经典界面里来回折腾按照这篇文章的安装和排查思路走一遍大概率能直接过渡到 JupyterLab。最后再分享一个小技巧装完 JupyterLab 后先别急着装插件用默认状态干一周活等你觉得哪个地方确实不顺了再去搜对应的扩展——这是让工具保持轻量、也让你自己的使用习惯沉淀下来的最好方式。
JupyterLab 从 Notebook 迁移、安装配置到避坑实战指南
这两年我从 Jupyter Notebook 切到 JupyterLab 之后最直接的感受就是我不用再同时开着五六个浏览器标签页来回找了。很多人第一次听说 JupyterLab都觉得它只是换了层皮的 Notebook实际上它是 Jupyter 生态里的新一代交互界面把文件管理、代码编辑、终端、数据查看这些东西全部收进了一个工作台里。对还在靠 Jupyter Notebook 写数据分析和教学演示的人来说把它当成日常主力工具完全够用而且迁移成本低到可以忽略——.ipynb文件直接打开就能用。这篇内容我会从安装路线开始讲覆盖 pip 和 Miniconda 两种方式、启动细节、界面功能、扩展配置最后把我实际用下来踩过的几个坑一并交代清楚。1. 从 Notebook 到 JupyterLab先搞清楚它到底“重”在哪、“轻”在哪1.1 最直观的区别一个页面是一个文档一个页面是一个工作台经典 Jupyter Notebook 的逻辑是“一个浏览器标签页 一个.ipynb文件”。我当年做一个小项目常常要同时打开数据清洗、特征工程、可视化三个 notebook结果就是标签页开了一排每个页面的菜单栏、工具栏、logo 全是重复的内存占用也跟着涨。JupyterLab 则完全不同。你启动之后看到的是一个类似 IDE 的单页应用SPA左侧是文件浏览器中间是编辑区右侧可以打开属性面板。你可以把两个 notebook 拖到同一屏幕左右分屏也可以一边开 notebook 一边在旁边的终端里跑 shell 命令不需要另外开窗口。它的定位不是“更好看的 Notebook”而是“一个能装下 Notebook 的工作台”。我第一次打开 JupyterLab 时的反应是“这也太空了”因为经典 Notebook 打开就是一个空白 cell而 JupyterLab 打开的是一个 Launcher 起始页上面有 Notebook、Python 文件、终端、控制台等入口。这个差异非常关键Notebook 默认只让你写 notebook而 JupyterLab 默认让你干很多种活。1.2 标题里说的“轻量替代”轻的不是体积很多人在评论区争论过JupyterLab 明明比 Notebook 多装了很多前端资源内存占用也更高凭什么叫“轻量替代”我自己的理解是标题里的“轻量”指的是使用体验上的轻不是资源占用上的轻。文件操作轻不需要为了打开一个.py文件或者查看 CSV 再去装别的编辑器文件浏览器里直接双击就能看。工作流切换轻从写代码到跑命令到看结果全部在一个窗口内完成不必跳来跳去。管理成本轻 Notebook 时代的jupyter notebook和ipython是不同命令JupyterLab 出来以后统一由 Jupyter Server 管理你只需要学 jupyter 这一条命令体系。反过来说如果你追求的是极致的启动速度和最低内存占用比如在只有 1G 内存的云服务器上跑那 JupyterLab 反而不如经典 Notebook 或者纯 IPython console。所以我的建议是本地开发、日常数据分析、教学演示用 JupyterLab服务器上临时开个交互环境可以继续用保守方案。1.3 它适合谁不适合谁我观察自己部门的同事觉得有三类人最适合从 Notebook 切到 JupyterLab写数据分析脚本的人每天跟 DataFrame、matplotlib 打交道需要在同一个工作区里来回调试。做课程演示或写教程的人JupyterLab 能把 Markdown、代码、图表和终端整合在一个窗口里演示的时候不容易手忙脚乱。觉得 VSCode 太重、只想开个浏览器就开始写的人JupyterLab 不需要配调试器和插件市场默认环境已经够用。不太适合的人是以大型软件工程为主、需要重度重构和复杂调试的开发者以及只是想随便记点笔记、不想碰代码的人。前者更适合 VSCode 或 PyCharm后者用普通 Markdown 编辑器就好。工具没有高低之分只有匹配度问题。2. 安装路线pip 和 Miniconda 到底怎么选2.1 装之前先确认你在哪个 Python 环境里很多人安装时出的问题根源根本不是 Jupyter 本身而是连自己用的是哪个 Python 都没搞清。Windows 上如果你装过 Anaconda又装过 Python.org 的官方包再叠一个 VS Code 自动装的 Python系统里通常会有好几个解释器。所以安装前先花一分钟确认环境# Windows 用 wheremacOS / Linux 用 which where python where pip # 查看版本和路径 python --version pip --version如果你用 Miniconda就先进对应的命令行工具Windows 上叫“Miniconda Prompt”或“Anaconda Prompt”再执行上面的命令。你会发现这里面的 python 路径指向你的 Miniconda 安装目录这很重要——之后所有包都要装到这个环境里别装到系统自带的另一个 Python 里去了否则会出现“装好了却启动不了”的诡异情况。2.2 最快跑通pip 安装 JupyterLab在没有 Conda 的机器上pip 是最快的路径pip install jupyterlab装完以后直接启动jupyter lab第一次启动会自动在浏览器打开http://localhost:8888/lab。如果没自动打开就把命令行里打印的 URL 手动复制到浏览器。这里有一个容易被老教程误导的点很多人以为装了 JupyterLab 之后jupyter notebook命令应该还能用。实际上新版 JupyterLab 是独立于经典 Notebook 包的如果你只装了jupyterlab运行jupyter notebook有可能提示找不到子命令。想继续用经典 Notebook 界面需要额外安装pip install notebook也就是说现在 Jupyter 生态里有两套界面内核和文件格式是共享的但前端是分开的。2.3 Miniconda 安装解决“装完不知道用哪个”的问题热词里有一条“miniconda安装后 如何使用jupyter notebook”这个我太有感触了因为这几乎是每个 Miniconda 新手都会碰到的事装完了 Miniconda开始菜单里有“Jupyter Notebook”快捷方式但点下去不是闪退就是报“找不到指定的程序”。原因通常是Miniconda 默认环境base里根本没装 notebook 或 jupyterlab开始菜单的快捷方式只是安装时帮你生成的脚本真正要跑起来得先安装对应包。正确的操作是这样# 先创建一个独立环境推荐别把包全都堆在 base conda create -n py311 python3.11 -y conda activate py311 # 再用 conda 安装 JupyterLab conda install -c conda-forge jupyterlab -y这样你的 py311 环境里就有了 JupyterLab。以后每次使用先执行conda activate py311再执行jupyter lab。如果你实在不想建环境直接装到 base 里也行conda install -c conda-forge jupyterlab -y但我真的不建议这么做。因为做数据分析的人往往会有多个项目每个项目依赖不同的包版本全都堆在 base 里早晚会冲突。用虚环境把 JupyterLab 装在项目环境里或者只在 base 装一个通用的 JupyterLab再通过内核机制引入其他环境这才是干净的做法。这个后面会专门讲。2.4 pip 和 conda 混装时的一个原则你如果用了 Miniconda我建议能conda install的优先用 conda实在 conda 上没有的包再用 pip。原因是 pip 和 conda 两套包管理器对文件的管理方式不同混装顺序不对可能互相覆盖。万一你在 conda 环境里已经用 pip 装了一半也不要慌JupyterLab 这种纯 Python 包通常不会出大问题真出问题就重装一遍pip uninstall jupyterlab -y conda install -c conda-forge jupyterlab -y3. 启动细节从命令行到浏览器还有那个“找不到指定的程序”3.1 jupyter lab 启动命令的常用参数最基本的启动就一条命令jupyter lab。但实际使用中下面这几个参数用的频率非常高# 指定其他端口适合 8888 被占用的情况 jupyter lab --port8889 # 启动时不自动打开浏览器适合在远程服务器上运行 jupyter lab --no-browser --port8888 # 指定工作目录打开后文件浏览器默认定位到该目录 jupyter lab --notebook-dirD:\projects\data # 允许所有 IP 访问谨慎使用通常搭配 token 认证 jupyter lab --ip0.0.0.0 --port8888这里我要强调--notebook-dir。很多人都是从桌面快捷方式直接点进 JupyterLab 的结果发现文件浏览器里显示的永远是某个固定目录找不到自己放代码的文件夹。你可以在启动命令里加上这个参数或者改配置文件后面讲不要傻乎乎地每次在文件浏览器里点半天目录层级。3.2 浏览器打不开时的处理思路JupyterLab 启动后终端里会打印一串 URL类似http://localhost:8888/lab?tokenxxxxxxxxxxxxxxxxxxxx如果浏览器没有自动打开原因无非三种浏览器阻止了自动弹出——手动复制 URL。你在远程服务器上——不能直接用 localhost要改成服务器的 IP。端口错误——--port8889会改变端口号但你还在尝试 8888。远程访问时一定要把 token 带上。token 就相当于你的访问凭证丢了的话可以从终端里翻也可以在配置里取消或重设。3.3 “Jupyter Notebook 启动时显示找不到指定的程序”排查链路这个报错在 Windows 上极其常见尤其是用 Miniconda 或 Anaconda 的用户。我在帮同事处理时见过五种不同原因完整的排查链路如下第一步分清报错出现的场景如果是点击开始菜单的“Jupyter Notebook”快捷方式报错多半是环境里没装对应包或者快捷方式指向的路径已经变了。如果在命令行里运行jupyter notebook报错才是真正的可执行文件或依赖问题。第二步命令行里验证 jupyter 是否可用jupyter --version如果提示“不是内部或外部命令”说明 Scripts 目录不在 PATH 里。Miniconda 用户出了这个问题可以在 Miniconda Prompt 里执行conda activate base conda install notebook jupyterlab -y第三步用绝对路径或 python -m 方式绕过 PATH 问题# 找到你的 python 路径后直接用模块方式启动 python -m jupyter lab python -m jupyter notebookpython -m的方式不依赖jupyter-notebook.exe是否在 PATH 中可以绕过很多快捷方式层面的问题。第四步检查环境是否错乱有些机器上装了多个 Python 版本Quick Launch 里的快捷方式指向的是某个已经被卸载的 Python 目录所以会报“找不到指定的程序”。打开快捷方式的属性看看“目标”一栏指向哪个路径如果路径不存在删除快捷方式重新在命令行里启动即可。第五步重装一次解决依赖残留pip uninstall jupyter jupyterlab notebook -y conda install -c conda-forge jupyterlab -y我见过一个案例用户之前从官网 Python 3.7 跑到 Miniconda 3.11系统里残留了一堆旧 jupyter 脚本重装一次立刻就好。第六步看看杀毒软件有没有拦截这一条属于玄学但真实发生Windows Defender 或第三方杀毒软件可能拦截 python.exe 或 jupyter 脚本生成临时文件。如果你重装后依然报错尝试把 Python 安装目录加入白名单再启动一次。4. 上手 JupyterLab界面布局和真正提升效率的日常操作4.1 工作台布局左侧文件浏览器和中间的 Launcher启动后默认界面左侧是文件浏览器中间是 Launcher 起始页。文件浏览器里能直接预览图片、CSV、JSON 等常见格式右键可以新建 folder、notebook、Python 文件、Markdown 文件也可以打开终端。这个设计比经典 Notebook 好了太多——你不需要先启动一个 notebook 才能写代码你可以先建.py文件跑通了再决定要不要转成 notebook。Launcher 里的几个入口值得留意Notebook新建.ipynb文件。Python File新建普通.py文件适合写正式脚本。Markdown File不只是 Notebook 里的 Markdown 单元格而是独立的.md文档。Terminal在浏览器里打开一个 shell 终端。Console打开一个 Python 控制台适合快速验证小段代码。我第一次用的时候最喜欢的是 Terminal因为以前用 Notebook 时想查个文件路径都要切到外部终端现在直接在同窗口里操作。4.2 多标签与拖拽分屏真正拉开差距的地方JupyterLab 允许你把任意标签页拖拽到工作区的任意区域形成上下或左右分屏。比如我在左边开一个数据处理的 notebook在右上角开一个 Markdown 文档用来记录想法在右下角再开一个 CSV 预览文件。三个区域互不干扰动任何一个都不会抢占焦点。这个功能在经典 Notebook 里是做不到的你只能用浏览器多窗口勉强模拟。对我这种习惯边写代码边对着数据文件核对逻辑的人来说拖拽分屏是最实用的一项。另一个很实用的小操作是Shift 左键点击第二个文件会将文件在右侧分屏打开不用手动拖拽适合快速对比两个 notebook。4.3 命令面板和快捷键是效率的核心经典 Notebook 时代大家记住的快捷键大多是单元格操作那套A 在上方插入、B 在下方插入、M 转 Markdown、Y 转 Code。JupyterLab 保留了这些而且多了一个“命令面板”。打开命令面板的默认快捷键是CtrlShiftCmacOS 是CmdShiftC也可以用菜单 View 里的 Activate Command Palette 打开。如果跟你系统快捷键冲突可以在设置里改。面板里几乎所有功能都能搜索新建、保存、关闭、切换布局、安装扩展、打开终端……我实际使用后最常用的搜索词反而是“Close”和“Split”因为鼠标点菜单太慢。下面是我平时会背下来的快捷键配合非常快操作快捷键运行当前单元格并移到下一格ShiftEnter运行当前单元格不动位置CtrlEnter运行当前并向下插入新格AltEnter执行代码补全Tab查看函数文档/签名ShiftTab切换命令模式/编辑模式Esc / Enter在上方插入单元格A在下方插入单元格B删除当前单元格连按两次 D单元格转 MarkdownM单元格转代码Y打开命令面板CtrlShiftC隐藏/显示左侧栏CtrlB注意删除单元格的 DD 是在命令模式下按的。如果你在编辑状态要先按 Esc 退出编辑再快速按两下 D否则会变成往单元格里敲字母。4.4 单元格执行状态和右侧属性面板在 Notebook 里运行代码时左侧会显示In [1]、In [2]这种序号正在运行的单元格会变成In [*]。这个逻辑和经典 Notebook 一样。JupyterLab 3.0 之后还在右侧加了属性面板可以查看当前选中单元格的类型、执行次数以及 notebook 的基础元信息。对于做教学的人来说这个面板可以方便你统一调整多个单元格的样式和运行配置不过平时用到的频率不算高。我更想提醒的是如果你在 JupyterLab 里打开了一个旧版内核生成的 notebook执行计数可能对不上这是正常现象不是 bug。内核执行计数是从当前会话开始计算的notebook 文件里记录的历史计数只是一个展示信息不对齐也无所谓。4.5 终端和中文用户需要注意的编码如果你在 Windows 上的 JupyterLab 终端里跑命令遇到中文乱码先检查时代码文件或命令行是不是 GBK 编码和 UTF-8 混了。在终端里执行chcp 65001切到 UTF-8 代码页能解决大部分中文显示问题。这个问题跟 JupyterLab 本身关系不大但第一次在浏览器终端里看到乱码时很懵所以写出来让大家少走弯路。5. 配置文件和扩展推荐让 JupyterLab 更顺手又不把它搞臃肿5.1 配置文件在哪怎么改JupyterLab 的配置是通过一个 Python 文件控制的可以用命令生成jupyter lab --generate-configWindows 下生成的文件在C:\Users\你的用户名\.jupyter\jupyter_lab_config.pymacOS / Linux 一般在~/.jupyter/jupyter_lab_config.py。打开这个文件常见的修改项如下# 端口 c.ServerApp.port 8888 # 自动打开浏览器 c.ServerApp.open_browser False # 默认工作目录 c.ServerApp.root_dir D:/projects # 设置空 token仅限本机使用远程别这么干 c.ServerApp.token 这里提醒一下老教程里动不动就让你改c.NotebookApp.token 那是经典 Notebook 时代的配置。新版 JupyterLab 是c.ServerApp两套配置项不完全互通。你如果在网上搜索时看到了c.NotebookApp先确认版本不要直接复制粘贴到jupyter_lab_config.py里否则不会生效。5.2 我常用的几个扩展装了不后悔卸载也不心疼JupyterLab 3.0 以后大部分扩展都能直接用pip安装不用再执行jupyter labextension install省了很多事。这里是我实测过、觉得值得装的一组# 图形化 Git 操作 pip install jupyterlab-git # 代码补全和诊断配合 python-lsp-server pip install jupyterlab-lsp pip install python-lsp-server # 显示每个单元格运行时间 pip install jupyterlab-execute-time # 支持直接画 drawio 流程图 pip install jupyterlab-drawio装完重启 JupyterLab 就能看到对应功能。jupyterlab-git会在左侧栏多出一个 Git 面板能看到文件变更、提交记录支持一键 commit/push。对于不想切到命令行的朋友很友好。jupyterlab-lsp是补全和跳转的关键。Python 用户配合python-lsp-server在 notebook 里写代码时补全提示更智能还能跳转到函数定义。jupyterlab-execute-time会在单元格下面显示耗时比如2.3s。我分析慢查询时全靠它定位瓶颈。jupyterlab-drawio不是数据分析必需但画流程图、脑图很好用。5.3 内核管理让所有 conda 环境都出现在 JupyterLab 里有一个非常常见的需求JupyterLab 装在 base 环境但我想用另一个 conda 环境 py311 里装的 pandas 版本。处理方法不是重新把 JupyterLab 装进每个环境而是给目标环境安装 ipykernel 并注册到 Jupyter 里# 先激活目标环境 conda activate py311 # 安装 ipykernel conda install ipykernel -y # 注册内核--display-name 是你在 JupyterLab 里看到的名字 python -m ipykernel install --user --namepy311 --display-name Python 3.11 (py311)以后新建 notebook 时内核选择列表里就会有“Python 3.11 (py311)”。这样 JupyterLab 只需要有一个通向所有环境的入口却可以很多个。5.4 别让扩展变成新的负担我曾经一口气装了七八个花里胡哨的扩展结果 JupyterLab 启动从几秒变成十几秒浏览器来回切面板还会卡。后来清理掉一半只留下 git、lsp、execute-time 这几个真正会用的。大家清理扩展时可以这样操作pip list | grep jupyterlab看到不常用的直接pip uninstall 包名。JupyterLab 的美妙恰恰在于它可以按需加装但“按需”这两个字是关键——装一堆用不上的就把“轻量”这个优势亲手丢掉了。6. 从 Notebook 迁移到 JupyterLab我实际踩过的几个坑6.1 ipynb 文件迁移其实不用迁移jupyter notebook保存的.ipynb文件和 JupyterLab 保存的.ipynb是同一个格式底层是 JSONJupyterLab 打开后直接进入新版界面不需要转换或导出。这一点对老用户来说是最舒服的你积累了一堆 notebook切换工具后照样打开。但有一点要注意如果你在经典 Notebook 里用了某些老版本的 nbconvert 魔法或自定义 JS 扩展迁移到 JupyterLab 后这些前端层面的东西大概率不兼容。我早年写过一个把单元格输出导出成特殊 HTML 的扩展切到 Lab 后就不生效了。解决办法是换个原生实现不要再依赖旧 Notebook 页面的注入脚本。6.2 双击 .ipynb 文件打不开或者打开了是旧 NotebookWindows 用户安装过 Anaconda、又装过 VS Code 之后系统里可能有多个程序抢着关联.ipynb文件。双击后经常直接打开 VSCode或者打开的是经典 Notebook 而不是 JupyterLab。我的做法是不要依赖双击打开文件先启动 JupyterLab再用左侧文件浏览器定位文件。这个几乎没有成本也能保证每次打开的都是 Lab 界面。如果你实在想双击就进 Lab可以在系统“默认应用”里把.ipynb关联到 JupyterLab 的可执行文件但不同版本路径差异大说实话不划算。6.3 内核一直显示 Connecting to Kernel换了 conda 环境后notebook 连不上内核是最容易遇到的。通常表现为单元格区域上方一直转圈写着 “Connecting to Kernel”。排查思路按顺序来确认内核名称是否存在于 Jupyter 内核列表里jupyter kernelspec list。如果不存在重新注册目标环境的内核看 5.3 节。如果存在但连不上多半是 ipykernel 版本和内核环境不匹配重新安装conda activate py311 conda install ipykernel --force-reinstall -y还有一种是旧内核缓存导致的。JupyterLab 设置面板里可以选择“重置内核”。重置之后问题基本都能解决。6.4 每次打开都在家目录想去项目目录怎么办如果你嫌每次启动后都要在文件浏览器里一层层点进去直接把启动命令改成jupyter lab --notebook-dirD:\projects\my_projectWindows 用户还可以做一个批处理文件放在桌面内容就是这一行命令双击即用它启动。比修改开始菜单快捷方式更可控。6.5 配置不生效改了半天没反应修改jupyter_lab_config.py后必须完全重启 JupyterLab 才生效。很多人改完配置直接刷新浏览器发现没用就是因为后台的 Jupyter Server 还跑着旧配置。重启时可以顺手把占用端口的旧进程杀掉# Windows 上查看 8888 端口占用 netstat -ano | findstr :8888 taskkill /PID 你的进程号 /F # macOS / Linux 上 lsof -i :8888 kill -9 进程号6.6 扩展装完看不到入口装了 jupyterlab-git 但左侧栏没出现 Git 面板多数是扩展没有安装到正确环境。JupyterLab 3.0 之后扩展与前端捆绑安装位置必须和 JupyterLab 本身在同一个 Python 环境。用pip list | grep jupyterlab-git确认扩展所在环境再确认 JupyterLab 启动也是这个环境。如果实在找不到入口去命令面板搜“Git”通常在“Settings 或 View”里能找到切换。或者重启一次浏览器端前端资源加载没刷新也会出现不显示的情况。我自己从 Notebook 切换过来后大概用了两周才彻底摆脱下意识开多个浏览器标签页的习惯。现在回头看JupyterLab 最值得称赞的一点是它没弄出另一套难学的交互方式而是把 Notebook 里已有的操作习惯原样保留同时在文件管理、终端、多面板这些环节补齐了我长期抱怨的短板。如果你手头已经有一堆.ipynb文件又受够了在经典界面里来回折腾按照这篇文章的安装和排查思路走一遍大概率能直接过渡到 JupyterLab。最后再分享一个小技巧装完 JupyterLab 后先别急着装插件用默认状态干一周活等你觉得哪个地方确实不顺了再去搜对应的扩展——这是让工具保持轻量、也让你自己的使用习惯沉淀下来的最好方式。
