1. 为什么我最终把 JupyterLab 当作日常主力而不是 Jupyter Notebook先说一个可能很多人都有同感的经历最早接触 Jupyter 生态时我用的还是老版的 Jupyter Notebook。那时觉得它已经够好了——能写代码、能跑结果、能插 Markdown 说明做一个数据分析任务绰绰有余。但用着用着问题就来了多开几个 notebook 之后浏览器标签页密密麻麻想在同一个项目里对比两份实验数据得在两个页面之间来回跳想打开一个终端跑点辅助命令还得分神去切到系统终端窗口。后来我转到 JupyterLab这个困扰才算真正解决。JupyterLab 可以理解为 Notebook 的完全体——它不是一个简单的升级版而是在同一个界面里把 notebook、终端、文本编辑器、文件管理、甚至数据查看器全部整合到一起。你在左边栏能看到整个项目目录中间可以并排打开多个 notebook右边还能挂一个终端窗口实时跑命令。这种一个工作台搞定所有事的体验一旦习惯就回不去了。不过我也得说句公道话Jupyter Notebook 虽然看起来老但它依然有不可替代的场景。比如很多教程、教材、线上课程还在用 Notebook 格式你跟着做作业时就必须用 Notebook 打开又比如你只想快速验证一小段代码不想开一个复杂的 IDENotebook 那种轻装上阵的感觉反而更舒服。更别说 Jupyter Notebook 的插件生态比如 nbextensions在某些功能上至今仍然比 JupyterLab 成熟。Voilà 则是另一个方向的延伸。它把 notebook 里的代码、输出和交互控件变成独立的 Web 应用读者看到的是干净的界面不需要看到背后的代码。换句话说JupyterLab 适合你自己干活Jupyter Notebook 适合跟随教程学习而 Voilà 适合把你做好的东西发布给不懂代码的人看。这三者不是取代关系而是分工关系。这篇指南的目标很具体我会从安装开始把三者的关系理清楚再把实际使用中最容易踩的坑和最少有人讲的细节一并交代。无论你是第一次接触 Jupyter 生态的新手还是已经用了 Notebook 很久、正在犹豫要不要转向 JupyterLab 的老用户这篇内容都能帮你节省不少试错时间。文章里的命令和步骤都是我在 Windows、macOS 和 Linux 三套环境上实测过的你照着操作基本不会翻车。2. 安装前的关键选择到底用 pip 还是 Anaconda2.1 两种安装方式的核心差异聊安装之前必须先决定一件事你用 pip 还是 Anaconda。这个选择会影响你后面的一切操作所以值得花点篇幅讲清楚。最简单的安装方式当然是 pip。只要你的电脑上已经有 Python 环境比如 Python 3.8 以上版本一条命令就能装好 JupyterLabpip install jupyterlab如果你是老派的 Notebook 使用者装这个pip install notebook两个都想装也可以pip install jupyterlab notebook但 pip 方式有一个隐藏问题它会把你现在的 Python 环境搞得比较乱。Jupyter 生态依赖一大堆底层库比如 tornado、pyzmq、nbformat、traitlets这些库的版本如果和你现有的项目冲突pip 通常会直接覆盖升级导致其他项目突然跑不起来。我有一次就是在某个环境里升级了 Jupyter 之后发现 Django 项目启动时报错查了半天才找到原因是某个底层依赖被悄悄换了版本。Anaconda 则完全不同。它内置了 Python 解释器、常用科学计算库NumPy、Pandas、Matplotlib、SciPy 等还自带 conda 作为包管理器。你装好 Anaconda 之后JupyterLab 和 Notebook 一般都已经预装好了直接用即可。就算要自己装也是用 conda 建一个独立环境互不干扰。如果你问我到底选哪个我的建议很简单新手、主要做数据分析/机器学习、不想折腾环境直接用 Anaconda。已经有较复杂的 Python 环境、只是偶尔写写 notebook、对依赖隔离很敏感用 pip最好配虚拟环境。已经熟悉 conda 那一套的conda 创建独立环境装 JupyterLab是目前最省心的组合。2.2 用 Anaconda 安装时的实操要点Anaconda 的安装过程本身没什么好讲的无非是去官网下载对应系统的安装包一路下一步。但有三个细节是我实际安装过很多次之后才总结出来的第一安装时如果遇到Add Anaconda3 to my PATH environment variable这个选项我的建议是不要勾选。很多人图方便会勾上结果后面使用中出现 conda 命令和系统原有 Python 冲突的概率非常高。正确做法是装完之后用 Anaconda PromptWindows或终端macOS/Linux进入 conda 环境再执行命令。第二安装路径不要带中文和空格。Conda 对路径的解析有时候很敏感路径里有空格还好说有中文就很容易出现莫名奇妙的编码错误。第三Anaconda 默认自带的 Jupyter 版本可能不是最新的。如果你需要最新版本不要直接在 base 环境里升级建议创建一个独立环境conda create -n jupyter-env python3.11 conda activate jupyter-env conda install jupyterlab notebook这样做的最大好处是这个环境专门服务 Jupyter无论怎么折腾都不会污染你的 base 环境。我平时做数据分析就用这个独立环境做其他开发时切换回 base 或其他环境互不干扰。2.3 pip 安装的进阶操作虚拟环境隔离如果你选择 pip我强烈建议你先创建一个虚拟环境。Python 自带的 venv 就够了不用额外装 virtualenvpython -m venv jupyter-venvWindows 下激活jupyter-venv\Scripts\activatemacOS/Linux 下激活source jupyter-venv/bin/activate然后在这个虚拟环境里安装pip install --upgrade pip pip install jupyterlab notebook这样一来你所有的 Jupyter 相关包都待在 jupyter-venv 这个独立目录里。即使某天你把整个环境删掉重来也不会影响系统的 Python。我有一次在项目里需要安装一个旧版本的 pandas直接在这个独立环境里随便装完全不担心影响其他项目这种安心感是全局安装永远给不了的。注意不管用哪种方式安装装完之后建议执行一次jupyter --version和jupyter lab --version确认版本号和可执行文件路径。如果输出里出现command not found或不是内部或外部命令多半是 PATH 没有配好优先检查安装方式是不是符合上面说的规则。3. JupyterLab 的启动、界面布局与日常使用流程3.1 启动方式与常见参数安装完成后启动 JupyterLab 非常简单。在终端或者 Anaconda Prompt、激活后的虚拟环境终端里执行jupyter lab执行完它会自动打开浏览器并访问类似http://localhost:8888的地址。如果你的电脑没有默认浏览器或者你想在指定浏览器里打开可以加参数jupyter lab --browserfirefox还有一些参数在实际使用中很有用。比如修改启动端口jupyter lab --port9999如果你在远程服务器上跑 JupyterLab想从本地浏览器访问需要加上jupyter lab --ip0.0.0.0 --no-browser然后本地浏览器访问http://服务器IP:8888。这里有个安全提醒远程访问时一定要设置密码否则等于把服务器裸奔在公网。设置密码的方式jupyter server password执行后按提示输入两次密码即可。它会生成一个哈希密码写入配置文件之后访问就需要认证了。我在实际部署中遇到过不少人忽略这一步结果服务器被扫描到后被人拿去跑挖矿程序切记切记。3.2 界面布局每个区域是干嘛的第一次打开 JupyterLab你可能会觉得界面比 Notebook 复杂不少。其实它的布局逻辑非常清晰从左到右主要是三块左侧是文件浏览器File Browser默认显示当前工作目录。你可以在这里新建文件夹、上传文件、新建 notebook、打开任意文本文件或图片。右键还能看到Open in Terminal直接在子目录打开终端这个功能在 Notebook 里是做不到的。中间是主工作区Main Work Area你可以把任意多个 notebook、终端、文本文件、图片拖到这里它们会以标签页的形式排列。最常用的操作是把两个 notebook 并排拖动到左右分栏这样就能实时对比两份实验结果。右侧是侧边栏Right Sidebar默认显示Properties属性面板可以查看当前 notebook 的 kernel、文件大小、最后保存时间等信息。此外还可以在这里打开Running Terminals and Kernels运行中的终端和内核面板方便你批量管理一堆会话。底部有一个状态栏显示当前 notebook 的内核状态idle/ busy、行号、内存使用等。我在调试长任务时经常盯着这个状态栏如果显示 busy 就知道代码还在跑如果变回 idle 就说明跑完了。3.3 日常使用流程从新建到导出的完整闭环我日常的使用流程一般是这样在左侧文件浏览器里选中目标目录点右键 → New → Notebook选择 Python 3 内核一个干净的 notebook 就建好了。在 notebook 里写代码时JupyterLab 的自动补全比 Notebook 强不少。默认按 Tab 键就能弹出补全列表并且很多第三方库的类型信息也能正确解析。我在 Notebook 里经常觉得补全不够聪明但在 JupyterLab 里明显准确很多。写完后我想把结果分享给同事看通常会用Export功能。JupyterLab 支持导出为 HTML、Markdown、PDF 等格式。路径在菜单栏 File → Export Notebook As。这里有个小坑导出 PDF 时如果系统里没有安装 LaTeX 引擎会直接报错。我自己一般不加 LaTeX而是先导出为 HTML再通过浏览器打印成 PDF效果差不多且少踩很多坑。如果你用的是 Jupyter Notebook也就是传统界面启动命令是jupyter notebook打开后的界面就简单多了一个文件列表页面点击 notebook 文件即可开始编辑。它没有 JupyterLab 那样的多标签、分栏和终端整合但对于单纯写代码和跟随教程学习完全够用。我至今仍保留 Notebook 的一个原因是某些老项目里用了 nbextensions 的扩展比如 table of contents、代码折叠这些扩展在 JupyterLab 里还没有完全的替代品。3.4 内核Kernel的概念为什么重要不管你用 JupyterLab 还是 Notebook都会频繁听到一个词Kernel内核。通俗点说Kernel 是真正执行代码的后台进程notebook 界面只是你写代码和看结果的前端。每个 notebook 右上角会显示当前使用的 Kernel 名称比如 Python 3 (ipykernel)。如果你安装了多个 Python 环境会发现每个环境可以注册自己的 Kernel在切换环境后 notebook 依然能认出它。我在多个环境之间切换时经常用到一个技巧把指定环境注册为 Jupyter Kernel。进入目标环境后执行python -m ipykernel install --user --name my-env --display-name My Env这样启动 Jupyter 后新建 notebook 时就能在 Kernel 列表中看到 My Env 选项。有了这个技巧我在一个 JupyterLab 里就能同时管理多个不同环境的 notebook而不用反复切换终端。我强烈建议每个用多环境的读者都掌握这个命令。另外如果一个 notebook 长时间无响应可以在菜单栏 Kernel → Restart Kernel 里重启内核内存就释放了。但注意重启内核会清空所有变量代码重新执行前那些中间结果就全没了所以重要数据一定要及时保存到文件。4. Voilà 的安装与 notebook 应用化实操4.1 Voilà 到底解决什么问题我最早听说 Voilà 是在一次内部工具分享会上。当时同事把一个数据筛选的 notebook 通过 Voilà 发布成了一个网页应用里面有一个下拉框、一个滑块拖一拖就能实时看到筛选后的图表。整个交互过程完全不需要看到代码发给业务部门的同事他们直接在浏览器里操作就行。当时给我的感觉是这不就是把 notebook 变成产品了吗后来我自己做数据分析经常遇到一个尴尬分析做完了图表也画好了但怎么分享给不会用 Jupyter 的领导直接发 ipynb 文件对方打不开也看不懂截图发过去又没法交互。Voilà 就是解决这个问题的它读取一个 notebook把里面的代码执行结果渲染成一个干净、独立的网页应用并且支持 ipywidgets 交互控件。所以Voilà 适合的场景是你想把一个 notebook 变成工具发给别人用把输入控件和输出展示封装成界面隐藏背后的代码逻辑。4.2 安装 Voilà 的完整步骤安装 Voilà 非常简单基于你已经装好 JupyterLab 的前提下pip install voila如果你想用 conda也可以conda install -c conda-forge voila启动方式有两种。第一种是直接在终端运行voila它会扫描当前目录下的所有 notebook 文件生成一个文件列表页面点击任意 notebook 就会以 Voilà 方式渲染。第二种更为常用如果你正在 JupyterLab 中编辑 notebook点击工具栏上的 Voilà 图标一个波浪线组成的图标就会在新标签页中打开该 notebook 的 Voilà 渲染结果。如果你在界面上找不到这个图标可能需要先启用 Voilà 的 JupyterLab 扩展jupyter labextension install jupyter-voila/jupyterlab-preview不过现在大多数版本安装voila时会自动安装配套扩展如果你装完发现没图标再执行上面这条命令即可。4.3 如何把 notebook 调整成适合 Voilà 展示的形态Voilà 默认会隐藏代码单元格只展示输出和交互控件。这带来一个微妙的问题如果你的 notebook 没有合理组织直接发布出来会比较乱。我总结了一套适合 Voilà 的 notebook 组织方法第一步把代码按逻辑分段。最理想的结构是最上方几个单元格导入库和加载数据中间的单元格定义处理函数最后一部分放交互控件和图表。这样 Voilà 按顺序从上往下执行每一段输出都会出现在对应的位置。第二步用 Widgets 构建交互控件。一个典型的滑块加图表示例import ipywidgets as widgets from IPython.display import display import matplotlib.pyplot as plt import numpy as np # 创建一个滑块 slider widgets.IntSlider(value50, min1, max100, description点数:) # 画出随滑块变化的图 def plot_points(count): plt.figure(figsize(6, 4)) x np.random.rand(count) y np.random.rand(count) plt.scatter(x, y) plt.title(f随机散点图{count} 个点) plt.show() # 通过 interact 将滑块和画图函数绑定 widgets.interact(plot_points, countslider)在 notebook 里运行这个单元格你会看到滑块和图表同时出现。Voilà 会自动把这种交互原样带到网页里读者拉动滑块图表实时变化完全不需要接触代码。第三步隐藏不必要的代码。Voilà 默认隐藏代码但你还可以通过 cell tag 的方式更精细地控制显示。具体做法是在 notebook 的单元格上添加 taghide_input这样即使某些单元格需要显示代码也能通过 tag 隐藏。JupyterLab 中给单元格添加 tag 的方法是选中单元格 → 右侧属性面板 → Add Tag。4.4 发布时的路径与参数注意启动 Voilà 时有一些参数值得提前知道。比如指定端口和 IPvoila --port8866 --ip0.0.0.0 --no-browser这在部署到服务器时非常常用能让团队其他成员通过浏览器访问。还有voila --templategridstack这个参数会启用 gridstack 模板把多个输出单元格以卡片布局排列适合做一个仪表盘风格的多图表页面。我试过这个模板视觉效果比默认模板好不少尤其是同时展示多张图表的场景下。如果你不想让所有人进入 Voilà 后看到文件列表想直接进入指定 notebook可以这样voila my_notebook.ipynb这样启动后会直接渲染指定的 notebook适合作为一个独立应用的入口。部署时我还会配合反向代理nginx把它映射到某个子路径不过那是后话普通使用不需要关心。4.5 Voilà 与 Streamlit / Dash 的取舍写到这里我想插一句实话不是所有 notebook 应用化场景都适合 Voilà。如果只是做一个简单的数据展示页Voilà 够用但如果你想做一个更复杂的 Web 应用比如多页面路由、用户登录、表单提交后写数据库Voilà 会比较吃力。这时我更推荐 Streamlit 或 Dash。不过 Voilà 有一个独特优势它基于 Jupyter 生态和学习成本几乎为零。你已经会用 notebook 写代码就相当于已经会写 Voilà 应用。Streamlit 和 Dash 则要求你去学一套新的 API 和状态管理逻辑。所以如果你的需求是快速把分析结果变成可交互的网页分享给别人Voilà 是性价比最高的选择如果未来要做的产品更复杂届时再迁移到 Streamlit 也不迟。5. 三者的关系与实战中的协同用法5.1 一个项目里让三件套各司其职很多人以为 JupyterLab、Notebook 和 Voilà 是三条平行线其实在一个完整项目中它们可以配合得非常默契。我这里用一个实际项目来演示假设我要做一个销售数据的月度异常检测分析。第一步我会在 JupyterLab 里创建项目目录录入数据文件。典型操作是打开 JupyterLab → 左侧 File Browser 导航到项目文件夹 → 上传 CSV 数据文件。接着新建一个 notebook开始探索性数据分析查看数据量、缺失值情况、分布特征。这段过程我会频繁使用 JupyterLab 的终端功能直接在终端里跑 pandas 的批处理脚本再回到 notebook 里做可视化。第二步分析思路定型后我可能把这个 notebook 按 Voilà 的要求重新组织加上滑块、下拉框等交互控件。比如加上一个月份选择器观众可以切换月份查看对应的销售额曲线加上一个异常阈值滑块拖动时可以标记出高于阈值的点。第三步我把这个 notebook 保存为sales_dashboard.ipynb然后通过 Voilà 发布。业务同事打开网页后直接操作完全不需要知道我背后用了什么模型。整个过程JupyterLab 是我的开发环境Notebook 是分析过程记录Voilà 则是最终交付物——三者不是互相替代而是串成了一条流水线。5.2 实际部署时需要注意的资源与安全问题把 Voilà 部署到服务器上时有几个细节我踩过坑拿出来说一下。第一Voilà 本质上是在启动一个 Jupyter 服务。如果你在服务器上以voila命令启动它默认会在你当前用户的家目录下寻找 notebook。如果你的数据文件在另一个目录建议在启动前先cd到目标目录否则渲染时会找不到相对路径的文件。第二Voilà 的每个会话都会执行一次 notebook 中的代码。如果 notebook 里有耗时的数据加载或模型训练步骤每打开一个会话就重新跑一次很容易把服务器内存打满。我的做法是尽量把费时的数据处理结果提前缓存成文件比如 CSV、parquet、pickleVoilà 渲染时只做读取和可视化避免每次打开页面都跑一遍全量计算。第三网络环境下的安全。Voilà 默认自带 token 认证启动时终端会打印一个访问 URL里面包含tokenxxx。如果你把这个 URL 发给别人对方就能访问。如果你想把 Voilà 挂在公网长期运行建议用反向代理并将 Voilà 绑定到127.0.0.1然后在 nginx 层面加 Basic Auth 或统一登录认证这样相对更稳妥。5.3 Notebook 与 JupyterLab 并存的日常习惯很多人会纠结要不要彻底用 JupyterLab 替换 Notebook。我的经验是不要非此即彼。JupyterLab 和 Notebook 可以并存而且并存时的体验更好因为你可以在 JupyterLab 里随时打开任意旧版 Notebook 格式的文件。JupyterLab 本身就能打开.ipynb文件而且渲染方式完全兼容所以不存在老文件打不开的问题。更值得一提的是JupyterLab 3.x 之后默认支持从界面查看 ipynb 文件的 JSON 源码右键 → Open With → JSON Editor这个功能对排查文件损坏问题很有用。如果某个 notebook 文件因为意外断电损坏用 JSON 编辑器打开通常还能恢复大部分内容。所以我现在的日常习惯是默认所有分析和开发都在 JupyterLab 里完成遇到需要跟随网上的教程操作时如果教程明确指定用 Jupyter Notebook我就直接打开 Notebook如果教程支持 JupyterLab我会直接用 JupyterLab 打开同一个文件。两个工具之间切换非常丝滑因为它们都遵循同一个.ipynb文件格式内核配置也完全互通。6. 高频报错、安装冲突与一定绕开的几个坑6.1 启动时提示找不到 jupyter 命令这是我在帮别人排查时遇到最多的一个问题。明明装的时候没报错但执行jupyter lab就是提示command not found或不是内部或外部命令。根本原因通常是 PATH 没有包含 Jupyter 可执行文件的目录。以 pip 安装为例Jupyter 的可执行文件一般装在 Python 的 Scripts 目录Windows或 bin 目录Linux/macOS。如果这个目录不在 PATH 里命令就找不到。解决思路有两种。一是把对应目录加入 PATH二是直接用模块方式启动绕过 PATH 问题python -m jupyterlab或者python -m jupyter lab通过python -m的方式启动一定会使用当前 Python 环境里的 Jupyter不会受到 PATH 混乱的影响。我在多个服务器上都用这个方式基本不会出问题。6.2 区别安装位置不一致造成的内核混乱你可能会遇到这样一种情况在终端里能正常进入 Python 并 import pandas但打开 JupyterLab 之后notebook 里import pandas却报 ModuleNotFoundError。这通常是内核Kernel对应的 Python 解释器和当前终端激活的 Python 不是同一个。我以前在这上面的教训比较深。有一次我在 base 环境装了 pandas然后创建了一个新 conda 环境激活新环境后启动了 JupyterLab结果 notebook 使用的还是 base 的 ipykernel——因为我没有在新环境里单独注册 kernelJupyterLab 默认读取的是先前注册过的。后来我学会了一个习惯在新环境里固定执行一次python -m ipykernel install --user --name my-newname --display-name My NewName确保 JupyterLab 里的 Kernel 列表中出现My NewName这个选项再启动 notebook 时手动选择它就彻底解决了这个混乱。6.3 Voilà 渲染时图表不显示的常见原因Voilà 渲染时最常见的坑是notebook 里能正常显示的 matplotlib 图表Voilà 页面里什么都不显示。原因之一是 matplotlib 默认的输出后端和 Voilà 不兼容。解决办法是在 notebook 开头执行%matplotlib inline把这行加进去之后matplotlib 的图表就会以内嵌形式输出Voilà 也能正常展示。如果你用了 seaborn它其实底层还是 matplotlib所以%matplotlib inline同样适用。另一个原因是代码单元格里用了plt.show()这本身没问题但有些版本的 Voilà 对动态输出的刷新有延迟。建议把plt.show()放在单元格最后不要和大量 print 语句混在一起避免渲染时的优先级冲突。6.4 pip 安装时的依赖冲突处理建议装了 JupyterLab 之后再装其他数据分析库时偶尔会提示依赖冲突。这种情况下我一般不建议强拆强装。优先做法是用虚拟环境隔离或直接改用 conda 环境。Conda 的依赖解析器比 pip 强不少它能自动帮你挑一套互不冲突的包版本。如果你已经在 conda 环境里可以执行conda install jupyterlab notebook voilaConda 会尝试找到兼容的组合。实在冲突且无法解决时再手动指定版本安装。比如pip install voila0.5.0这种手动锁版本的方式会让环境更可控但也意味着后续升级时可能还有冲突所以我始终强调环境隔离优先于强行统一版本。6.5 Windows 用户特有的坑编码与路径问题Windows 上使用 Jupyter 时我遇到最多的是路径编码问题。如果你的用户名或项目路径包含中文有些库在读写文件时可能报 UnicodeDecodeError 或 FileNotFoundError。这个问题在 Jupyter 自身处理得还行但在某些扩展库尤其是老版本 Pandas身上比较明显。我的建议是项目目录尽量用英文文件名也尽量不用中文。这不是什么高科技但确实能省掉很多莫名其妙的报错。如果你接手了一个已存在中文路径的项目可以在 notebook 开头设置import sys import io sys.stdout io.TextIOWrapper(sys.stdout.buffer, encodingutf-8)这样可以缓解一部分中文编码问题但最好的解决方案还是从源头规避。7. 扩展配置token、密码、远程访问与常用插件7.1 登录安全配置token 与密码JupyterLab 和 Notebook 默认启动时会生成一个 tokenURL 里会显示。这个 token 相当于你访问服务的凭证。如果你觉得每次复制 URL 带 token 太麻烦可以设置固定密码。最推荐的方式还是在终端里执行jupyter server password输入两遍密码后它会自动写入配置文件~/.jupyter/jupyter_server_config.json。之后启动 JupyterLab 访问时就可以用这个密码登录而不需要 URL 里带 token。如果你想手动配置自定义端口、IP、是否允许远程访问可以生成配置文件再修改jupyter server --generate-config生成的文件位于~/.jupyter/jupyter_server_config.py。打开后找到对应的配置项修改即可。常用配置通常包括c.ServerApp.ip 0.0.0.0 c.ServerApp.port 8888 c.ServerApp.open_browser False c.ServerApp.allow_remote_access True这里我提醒一下allow_remote_access True意味着可以从外部访问如果是在敏感网络或公网环境一定要配上密码并且最好用防火墙把端口限定在内网可访问。7.2 常用插件我实际在用的几款JupyterLab 的扩展机制让它比 Notebook 更灵活。插件安装方式很简单在 JupyterLab 界面里进入 Extension Manager搜索插件名称点 Install 即可。我实际用下来觉得值得装的插件有这些Table of Contents自动生成 notebook 标题目录长文档导航神器。jupyterlab-git在界面里直接进行 Git 操作查看 diff、提交和推送方便到不用开命令行。jupyterlab-spreadsheet在 JupyterLab 里直接预览 CSV 文件双击就能看到表格不用每次都用 pandas 读一遍。jupyterlab/toc左侧目录树配合长 notebook 使用体验极佳。jupyterlab-variableinspector边写代码边看当前环境里所有变量的值调试时会省很多事。Notebook 那边也有不少经典扩展比如 nbextensions 里的 Table of Contents、Collapsible Headings、Codefolding。但这些插件的安装方式使用 pip 安装jupyter_contrib_nbextensions后启用比较折腾而且和 JupyterLab 的扩展机制完全不同。所以我建议新用户直接拥抱 JupyterLab 的扩展生态即可不必再花时间折腾老插件。7.3 远程访问与反向代理更优雅的部署方式如果你在云服务器上使用 Jupyter 生态除了直接在公网监听端口之外我更推荐的部署方式是用反向代理。以 nginx 为例可以这样配置一个子路径代理location /jupyter/ { proxy_pass http://127.0.0.1:8888/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; }注意 JupyterLab 使用 WebSocket 进行实时通信所以必须配置Upgrade和Connection头否则前端可能出现connection closed的报错。这种部署的好处是你可以通过https://域名/jupyter/统一入口访问并且可以在 nginx 层做访问控制、配置 SSL、把多个服务如 JupyterLab 和 Voilà映射到不同路径管理起来更规范。如果你前面已经设置了 Jupyter 密码外部访问的安全性就有了双重保障。8. 从 notebook 迁移到 JupyterLab我给你的平滑转型建议8.1 别着急切环境先从混用开始不少朋友问我要不要把手头所有 Notebook 项目都迁到 JupyterLab我的回答是不用着急先从混用开始。JupyterLab 打开.ipynb文件完全兼容旧格式你直接拿 JupyterLab 打开原本在 Notebook 里写的文件代码和输出都会原样显示。早期你不需要做任何迁移工作只需要在日常操作中慢慢增加 JupyterLab 的使用比例新建的项目优先在 JupyterLab 里做只有打开旧的、依赖老插件的文件时才切回 Notebook。我还建议你把平时常用的命令记下来比如jupyter lab、jupyter notebook、jupyter server password、python -m ipykernel install以及voila。时间久了你会形成一种肌肉记忆需要开发环境时打开 JupyterLab需要快速测试时打开 Notebook需要分享交付时跑 Voilà。三者随时可以切换不存在只能选一个的问题。8.2 文件整理与目录结构的建议Jupyter 生态的项目目录最好一开始就规划好。我自己的典型结构是这样的project/ ├── data/ │ ├── raw/ │ └── processed/ ├── notebooks/ │ ├── 01_explore.ipynb │ ├── 02_model.ipynb │ └── dashboard.ipynb ├── scripts/ │ ├── preprocess.py │ └── utils.py ├── output/ │ ├── figures/ │ └── reports/ └── README.md这样的好处是Voilà 发布时只需要指定notebooks/dashboard.ipynb数据路径统一从data/读取不会出现代码在 notebook 里能跑在 Voilà 里找不到文件的悲剧。脚本和 notebook 分离也让项目更容易回溯和维护。8.3 备份与版本管理Jupyter notebook 文件是 JSON 格式每次保存都会生成一个快照。但多人协作或自己长期迭代时强烈建议用 Git 做版本管理。你可以在 JupyterLab 的终端里对项目目录执行git init然后配合前面提到的 jupyterlab-git 插件在界面里直接提交。这样每次改动都有历史随时可以回退。另外要提醒的是.ipynb文件里会保存执行输出输出里如果包含了大量图片会让 Git diff 变得非常难读。如果团队协作严格建议在 Git 客户端里启用nbstripout工具在提交前剥离输出只保留代码和 markdown能显著减小仓库体积也让代码审查更聚焦。我自己的习惯是本地保留完整输出提交到远程仓库时用nbstripout清理需要展示结果时再通过 Voilà 生成网页给最终受众。9. 个人使用体会与下一步可以尝试的方向如果让我用一个比喻来总结 JupyterLab、Notebook 和 Voilà 的关系Notebook 是厨房里的炒锅JupyterLab 是整间厨房Voilà 则是把做好的菜端到餐厅给客人品尝。这三件事在不同阶段出现解决的是不同层次的问题它们之间并不冲突反而是我目前见过的最有效率的数据工作流之一。最后分享一个我最近在尝试的方向把 Voilà 发布的应用和定时任务结合起来。比如用 cron 在每天凌晨自动跑数据更新脚本输出最新的分析结果到output/目录Voilà 每次打开时不重新计算而是读取已经刷新好的数据文件。这样一来团队每天打开应用看到的都是昨天的数据而服务器资源消耗几乎为零。如果你已经完成了本文里的安装和使用流程我很建议你往这个方向再走一步——它会让你的数据产品从能用进化到真正能持续运行。希望这篇东西对你的 Jupyter 之路有实实在在的帮助。遇到具体报错时优先回看环境隔离、内核选择、文件路径这几个最容易被忽视的环节多数问题都能在那里找到答案。
JupyterLab、Notebook与Voilà：数据科学工作流的正确打开方式
1. 为什么我最终把 JupyterLab 当作日常主力而不是 Jupyter Notebook先说一个可能很多人都有同感的经历最早接触 Jupyter 生态时我用的还是老版的 Jupyter Notebook。那时觉得它已经够好了——能写代码、能跑结果、能插 Markdown 说明做一个数据分析任务绰绰有余。但用着用着问题就来了多开几个 notebook 之后浏览器标签页密密麻麻想在同一个项目里对比两份实验数据得在两个页面之间来回跳想打开一个终端跑点辅助命令还得分神去切到系统终端窗口。后来我转到 JupyterLab这个困扰才算真正解决。JupyterLab 可以理解为 Notebook 的完全体——它不是一个简单的升级版而是在同一个界面里把 notebook、终端、文本编辑器、文件管理、甚至数据查看器全部整合到一起。你在左边栏能看到整个项目目录中间可以并排打开多个 notebook右边还能挂一个终端窗口实时跑命令。这种一个工作台搞定所有事的体验一旦习惯就回不去了。不过我也得说句公道话Jupyter Notebook 虽然看起来老但它依然有不可替代的场景。比如很多教程、教材、线上课程还在用 Notebook 格式你跟着做作业时就必须用 Notebook 打开又比如你只想快速验证一小段代码不想开一个复杂的 IDENotebook 那种轻装上阵的感觉反而更舒服。更别说 Jupyter Notebook 的插件生态比如 nbextensions在某些功能上至今仍然比 JupyterLab 成熟。Voilà 则是另一个方向的延伸。它把 notebook 里的代码、输出和交互控件变成独立的 Web 应用读者看到的是干净的界面不需要看到背后的代码。换句话说JupyterLab 适合你自己干活Jupyter Notebook 适合跟随教程学习而 Voilà 适合把你做好的东西发布给不懂代码的人看。这三者不是取代关系而是分工关系。这篇指南的目标很具体我会从安装开始把三者的关系理清楚再把实际使用中最容易踩的坑和最少有人讲的细节一并交代。无论你是第一次接触 Jupyter 生态的新手还是已经用了 Notebook 很久、正在犹豫要不要转向 JupyterLab 的老用户这篇内容都能帮你节省不少试错时间。文章里的命令和步骤都是我在 Windows、macOS 和 Linux 三套环境上实测过的你照着操作基本不会翻车。2. 安装前的关键选择到底用 pip 还是 Anaconda2.1 两种安装方式的核心差异聊安装之前必须先决定一件事你用 pip 还是 Anaconda。这个选择会影响你后面的一切操作所以值得花点篇幅讲清楚。最简单的安装方式当然是 pip。只要你的电脑上已经有 Python 环境比如 Python 3.8 以上版本一条命令就能装好 JupyterLabpip install jupyterlab如果你是老派的 Notebook 使用者装这个pip install notebook两个都想装也可以pip install jupyterlab notebook但 pip 方式有一个隐藏问题它会把你现在的 Python 环境搞得比较乱。Jupyter 生态依赖一大堆底层库比如 tornado、pyzmq、nbformat、traitlets这些库的版本如果和你现有的项目冲突pip 通常会直接覆盖升级导致其他项目突然跑不起来。我有一次就是在某个环境里升级了 Jupyter 之后发现 Django 项目启动时报错查了半天才找到原因是某个底层依赖被悄悄换了版本。Anaconda 则完全不同。它内置了 Python 解释器、常用科学计算库NumPy、Pandas、Matplotlib、SciPy 等还自带 conda 作为包管理器。你装好 Anaconda 之后JupyterLab 和 Notebook 一般都已经预装好了直接用即可。就算要自己装也是用 conda 建一个独立环境互不干扰。如果你问我到底选哪个我的建议很简单新手、主要做数据分析/机器学习、不想折腾环境直接用 Anaconda。已经有较复杂的 Python 环境、只是偶尔写写 notebook、对依赖隔离很敏感用 pip最好配虚拟环境。已经熟悉 conda 那一套的conda 创建独立环境装 JupyterLab是目前最省心的组合。2.2 用 Anaconda 安装时的实操要点Anaconda 的安装过程本身没什么好讲的无非是去官网下载对应系统的安装包一路下一步。但有三个细节是我实际安装过很多次之后才总结出来的第一安装时如果遇到Add Anaconda3 to my PATH environment variable这个选项我的建议是不要勾选。很多人图方便会勾上结果后面使用中出现 conda 命令和系统原有 Python 冲突的概率非常高。正确做法是装完之后用 Anaconda PromptWindows或终端macOS/Linux进入 conda 环境再执行命令。第二安装路径不要带中文和空格。Conda 对路径的解析有时候很敏感路径里有空格还好说有中文就很容易出现莫名奇妙的编码错误。第三Anaconda 默认自带的 Jupyter 版本可能不是最新的。如果你需要最新版本不要直接在 base 环境里升级建议创建一个独立环境conda create -n jupyter-env python3.11 conda activate jupyter-env conda install jupyterlab notebook这样做的最大好处是这个环境专门服务 Jupyter无论怎么折腾都不会污染你的 base 环境。我平时做数据分析就用这个独立环境做其他开发时切换回 base 或其他环境互不干扰。2.3 pip 安装的进阶操作虚拟环境隔离如果你选择 pip我强烈建议你先创建一个虚拟环境。Python 自带的 venv 就够了不用额外装 virtualenvpython -m venv jupyter-venvWindows 下激活jupyter-venv\Scripts\activatemacOS/Linux 下激活source jupyter-venv/bin/activate然后在这个虚拟环境里安装pip install --upgrade pip pip install jupyterlab notebook这样一来你所有的 Jupyter 相关包都待在 jupyter-venv 这个独立目录里。即使某天你把整个环境删掉重来也不会影响系统的 Python。我有一次在项目里需要安装一个旧版本的 pandas直接在这个独立环境里随便装完全不担心影响其他项目这种安心感是全局安装永远给不了的。注意不管用哪种方式安装装完之后建议执行一次jupyter --version和jupyter lab --version确认版本号和可执行文件路径。如果输出里出现command not found或不是内部或外部命令多半是 PATH 没有配好优先检查安装方式是不是符合上面说的规则。3. JupyterLab 的启动、界面布局与日常使用流程3.1 启动方式与常见参数安装完成后启动 JupyterLab 非常简单。在终端或者 Anaconda Prompt、激活后的虚拟环境终端里执行jupyter lab执行完它会自动打开浏览器并访问类似http://localhost:8888的地址。如果你的电脑没有默认浏览器或者你想在指定浏览器里打开可以加参数jupyter lab --browserfirefox还有一些参数在实际使用中很有用。比如修改启动端口jupyter lab --port9999如果你在远程服务器上跑 JupyterLab想从本地浏览器访问需要加上jupyter lab --ip0.0.0.0 --no-browser然后本地浏览器访问http://服务器IP:8888。这里有个安全提醒远程访问时一定要设置密码否则等于把服务器裸奔在公网。设置密码的方式jupyter server password执行后按提示输入两次密码即可。它会生成一个哈希密码写入配置文件之后访问就需要认证了。我在实际部署中遇到过不少人忽略这一步结果服务器被扫描到后被人拿去跑挖矿程序切记切记。3.2 界面布局每个区域是干嘛的第一次打开 JupyterLab你可能会觉得界面比 Notebook 复杂不少。其实它的布局逻辑非常清晰从左到右主要是三块左侧是文件浏览器File Browser默认显示当前工作目录。你可以在这里新建文件夹、上传文件、新建 notebook、打开任意文本文件或图片。右键还能看到Open in Terminal直接在子目录打开终端这个功能在 Notebook 里是做不到的。中间是主工作区Main Work Area你可以把任意多个 notebook、终端、文本文件、图片拖到这里它们会以标签页的形式排列。最常用的操作是把两个 notebook 并排拖动到左右分栏这样就能实时对比两份实验结果。右侧是侧边栏Right Sidebar默认显示Properties属性面板可以查看当前 notebook 的 kernel、文件大小、最后保存时间等信息。此外还可以在这里打开Running Terminals and Kernels运行中的终端和内核面板方便你批量管理一堆会话。底部有一个状态栏显示当前 notebook 的内核状态idle/ busy、行号、内存使用等。我在调试长任务时经常盯着这个状态栏如果显示 busy 就知道代码还在跑如果变回 idle 就说明跑完了。3.3 日常使用流程从新建到导出的完整闭环我日常的使用流程一般是这样在左侧文件浏览器里选中目标目录点右键 → New → Notebook选择 Python 3 内核一个干净的 notebook 就建好了。在 notebook 里写代码时JupyterLab 的自动补全比 Notebook 强不少。默认按 Tab 键就能弹出补全列表并且很多第三方库的类型信息也能正确解析。我在 Notebook 里经常觉得补全不够聪明但在 JupyterLab 里明显准确很多。写完后我想把结果分享给同事看通常会用Export功能。JupyterLab 支持导出为 HTML、Markdown、PDF 等格式。路径在菜单栏 File → Export Notebook As。这里有个小坑导出 PDF 时如果系统里没有安装 LaTeX 引擎会直接报错。我自己一般不加 LaTeX而是先导出为 HTML再通过浏览器打印成 PDF效果差不多且少踩很多坑。如果你用的是 Jupyter Notebook也就是传统界面启动命令是jupyter notebook打开后的界面就简单多了一个文件列表页面点击 notebook 文件即可开始编辑。它没有 JupyterLab 那样的多标签、分栏和终端整合但对于单纯写代码和跟随教程学习完全够用。我至今仍保留 Notebook 的一个原因是某些老项目里用了 nbextensions 的扩展比如 table of contents、代码折叠这些扩展在 JupyterLab 里还没有完全的替代品。3.4 内核Kernel的概念为什么重要不管你用 JupyterLab 还是 Notebook都会频繁听到一个词Kernel内核。通俗点说Kernel 是真正执行代码的后台进程notebook 界面只是你写代码和看结果的前端。每个 notebook 右上角会显示当前使用的 Kernel 名称比如 Python 3 (ipykernel)。如果你安装了多个 Python 环境会发现每个环境可以注册自己的 Kernel在切换环境后 notebook 依然能认出它。我在多个环境之间切换时经常用到一个技巧把指定环境注册为 Jupyter Kernel。进入目标环境后执行python -m ipykernel install --user --name my-env --display-name My Env这样启动 Jupyter 后新建 notebook 时就能在 Kernel 列表中看到 My Env 选项。有了这个技巧我在一个 JupyterLab 里就能同时管理多个不同环境的 notebook而不用反复切换终端。我强烈建议每个用多环境的读者都掌握这个命令。另外如果一个 notebook 长时间无响应可以在菜单栏 Kernel → Restart Kernel 里重启内核内存就释放了。但注意重启内核会清空所有变量代码重新执行前那些中间结果就全没了所以重要数据一定要及时保存到文件。4. Voilà 的安装与 notebook 应用化实操4.1 Voilà 到底解决什么问题我最早听说 Voilà 是在一次内部工具分享会上。当时同事把一个数据筛选的 notebook 通过 Voilà 发布成了一个网页应用里面有一个下拉框、一个滑块拖一拖就能实时看到筛选后的图表。整个交互过程完全不需要看到代码发给业务部门的同事他们直接在浏览器里操作就行。当时给我的感觉是这不就是把 notebook 变成产品了吗后来我自己做数据分析经常遇到一个尴尬分析做完了图表也画好了但怎么分享给不会用 Jupyter 的领导直接发 ipynb 文件对方打不开也看不懂截图发过去又没法交互。Voilà 就是解决这个问题的它读取一个 notebook把里面的代码执行结果渲染成一个干净、独立的网页应用并且支持 ipywidgets 交互控件。所以Voilà 适合的场景是你想把一个 notebook 变成工具发给别人用把输入控件和输出展示封装成界面隐藏背后的代码逻辑。4.2 安装 Voilà 的完整步骤安装 Voilà 非常简单基于你已经装好 JupyterLab 的前提下pip install voila如果你想用 conda也可以conda install -c conda-forge voila启动方式有两种。第一种是直接在终端运行voila它会扫描当前目录下的所有 notebook 文件生成一个文件列表页面点击任意 notebook 就会以 Voilà 方式渲染。第二种更为常用如果你正在 JupyterLab 中编辑 notebook点击工具栏上的 Voilà 图标一个波浪线组成的图标就会在新标签页中打开该 notebook 的 Voilà 渲染结果。如果你在界面上找不到这个图标可能需要先启用 Voilà 的 JupyterLab 扩展jupyter labextension install jupyter-voila/jupyterlab-preview不过现在大多数版本安装voila时会自动安装配套扩展如果你装完发现没图标再执行上面这条命令即可。4.3 如何把 notebook 调整成适合 Voilà 展示的形态Voilà 默认会隐藏代码单元格只展示输出和交互控件。这带来一个微妙的问题如果你的 notebook 没有合理组织直接发布出来会比较乱。我总结了一套适合 Voilà 的 notebook 组织方法第一步把代码按逻辑分段。最理想的结构是最上方几个单元格导入库和加载数据中间的单元格定义处理函数最后一部分放交互控件和图表。这样 Voilà 按顺序从上往下执行每一段输出都会出现在对应的位置。第二步用 Widgets 构建交互控件。一个典型的滑块加图表示例import ipywidgets as widgets from IPython.display import display import matplotlib.pyplot as plt import numpy as np # 创建一个滑块 slider widgets.IntSlider(value50, min1, max100, description点数:) # 画出随滑块变化的图 def plot_points(count): plt.figure(figsize(6, 4)) x np.random.rand(count) y np.random.rand(count) plt.scatter(x, y) plt.title(f随机散点图{count} 个点) plt.show() # 通过 interact 将滑块和画图函数绑定 widgets.interact(plot_points, countslider)在 notebook 里运行这个单元格你会看到滑块和图表同时出现。Voilà 会自动把这种交互原样带到网页里读者拉动滑块图表实时变化完全不需要接触代码。第三步隐藏不必要的代码。Voilà 默认隐藏代码但你还可以通过 cell tag 的方式更精细地控制显示。具体做法是在 notebook 的单元格上添加 taghide_input这样即使某些单元格需要显示代码也能通过 tag 隐藏。JupyterLab 中给单元格添加 tag 的方法是选中单元格 → 右侧属性面板 → Add Tag。4.4 发布时的路径与参数注意启动 Voilà 时有一些参数值得提前知道。比如指定端口和 IPvoila --port8866 --ip0.0.0.0 --no-browser这在部署到服务器时非常常用能让团队其他成员通过浏览器访问。还有voila --templategridstack这个参数会启用 gridstack 模板把多个输出单元格以卡片布局排列适合做一个仪表盘风格的多图表页面。我试过这个模板视觉效果比默认模板好不少尤其是同时展示多张图表的场景下。如果你不想让所有人进入 Voilà 后看到文件列表想直接进入指定 notebook可以这样voila my_notebook.ipynb这样启动后会直接渲染指定的 notebook适合作为一个独立应用的入口。部署时我还会配合反向代理nginx把它映射到某个子路径不过那是后话普通使用不需要关心。4.5 Voilà 与 Streamlit / Dash 的取舍写到这里我想插一句实话不是所有 notebook 应用化场景都适合 Voilà。如果只是做一个简单的数据展示页Voilà 够用但如果你想做一个更复杂的 Web 应用比如多页面路由、用户登录、表单提交后写数据库Voilà 会比较吃力。这时我更推荐 Streamlit 或 Dash。不过 Voilà 有一个独特优势它基于 Jupyter 生态和学习成本几乎为零。你已经会用 notebook 写代码就相当于已经会写 Voilà 应用。Streamlit 和 Dash 则要求你去学一套新的 API 和状态管理逻辑。所以如果你的需求是快速把分析结果变成可交互的网页分享给别人Voilà 是性价比最高的选择如果未来要做的产品更复杂届时再迁移到 Streamlit 也不迟。5. 三者的关系与实战中的协同用法5.1 一个项目里让三件套各司其职很多人以为 JupyterLab、Notebook 和 Voilà 是三条平行线其实在一个完整项目中它们可以配合得非常默契。我这里用一个实际项目来演示假设我要做一个销售数据的月度异常检测分析。第一步我会在 JupyterLab 里创建项目目录录入数据文件。典型操作是打开 JupyterLab → 左侧 File Browser 导航到项目文件夹 → 上传 CSV 数据文件。接着新建一个 notebook开始探索性数据分析查看数据量、缺失值情况、分布特征。这段过程我会频繁使用 JupyterLab 的终端功能直接在终端里跑 pandas 的批处理脚本再回到 notebook 里做可视化。第二步分析思路定型后我可能把这个 notebook 按 Voilà 的要求重新组织加上滑块、下拉框等交互控件。比如加上一个月份选择器观众可以切换月份查看对应的销售额曲线加上一个异常阈值滑块拖动时可以标记出高于阈值的点。第三步我把这个 notebook 保存为sales_dashboard.ipynb然后通过 Voilà 发布。业务同事打开网页后直接操作完全不需要知道我背后用了什么模型。整个过程JupyterLab 是我的开发环境Notebook 是分析过程记录Voilà 则是最终交付物——三者不是互相替代而是串成了一条流水线。5.2 实际部署时需要注意的资源与安全问题把 Voilà 部署到服务器上时有几个细节我踩过坑拿出来说一下。第一Voilà 本质上是在启动一个 Jupyter 服务。如果你在服务器上以voila命令启动它默认会在你当前用户的家目录下寻找 notebook。如果你的数据文件在另一个目录建议在启动前先cd到目标目录否则渲染时会找不到相对路径的文件。第二Voilà 的每个会话都会执行一次 notebook 中的代码。如果 notebook 里有耗时的数据加载或模型训练步骤每打开一个会话就重新跑一次很容易把服务器内存打满。我的做法是尽量把费时的数据处理结果提前缓存成文件比如 CSV、parquet、pickleVoilà 渲染时只做读取和可视化避免每次打开页面都跑一遍全量计算。第三网络环境下的安全。Voilà 默认自带 token 认证启动时终端会打印一个访问 URL里面包含tokenxxx。如果你把这个 URL 发给别人对方就能访问。如果你想把 Voilà 挂在公网长期运行建议用反向代理并将 Voilà 绑定到127.0.0.1然后在 nginx 层面加 Basic Auth 或统一登录认证这样相对更稳妥。5.3 Notebook 与 JupyterLab 并存的日常习惯很多人会纠结要不要彻底用 JupyterLab 替换 Notebook。我的经验是不要非此即彼。JupyterLab 和 Notebook 可以并存而且并存时的体验更好因为你可以在 JupyterLab 里随时打开任意旧版 Notebook 格式的文件。JupyterLab 本身就能打开.ipynb文件而且渲染方式完全兼容所以不存在老文件打不开的问题。更值得一提的是JupyterLab 3.x 之后默认支持从界面查看 ipynb 文件的 JSON 源码右键 → Open With → JSON Editor这个功能对排查文件损坏问题很有用。如果某个 notebook 文件因为意外断电损坏用 JSON 编辑器打开通常还能恢复大部分内容。所以我现在的日常习惯是默认所有分析和开发都在 JupyterLab 里完成遇到需要跟随网上的教程操作时如果教程明确指定用 Jupyter Notebook我就直接打开 Notebook如果教程支持 JupyterLab我会直接用 JupyterLab 打开同一个文件。两个工具之间切换非常丝滑因为它们都遵循同一个.ipynb文件格式内核配置也完全互通。6. 高频报错、安装冲突与一定绕开的几个坑6.1 启动时提示找不到 jupyter 命令这是我在帮别人排查时遇到最多的一个问题。明明装的时候没报错但执行jupyter lab就是提示command not found或不是内部或外部命令。根本原因通常是 PATH 没有包含 Jupyter 可执行文件的目录。以 pip 安装为例Jupyter 的可执行文件一般装在 Python 的 Scripts 目录Windows或 bin 目录Linux/macOS。如果这个目录不在 PATH 里命令就找不到。解决思路有两种。一是把对应目录加入 PATH二是直接用模块方式启动绕过 PATH 问题python -m jupyterlab或者python -m jupyter lab通过python -m的方式启动一定会使用当前 Python 环境里的 Jupyter不会受到 PATH 混乱的影响。我在多个服务器上都用这个方式基本不会出问题。6.2 区别安装位置不一致造成的内核混乱你可能会遇到这样一种情况在终端里能正常进入 Python 并 import pandas但打开 JupyterLab 之后notebook 里import pandas却报 ModuleNotFoundError。这通常是内核Kernel对应的 Python 解释器和当前终端激活的 Python 不是同一个。我以前在这上面的教训比较深。有一次我在 base 环境装了 pandas然后创建了一个新 conda 环境激活新环境后启动了 JupyterLab结果 notebook 使用的还是 base 的 ipykernel——因为我没有在新环境里单独注册 kernelJupyterLab 默认读取的是先前注册过的。后来我学会了一个习惯在新环境里固定执行一次python -m ipykernel install --user --name my-newname --display-name My NewName确保 JupyterLab 里的 Kernel 列表中出现My NewName这个选项再启动 notebook 时手动选择它就彻底解决了这个混乱。6.3 Voilà 渲染时图表不显示的常见原因Voilà 渲染时最常见的坑是notebook 里能正常显示的 matplotlib 图表Voilà 页面里什么都不显示。原因之一是 matplotlib 默认的输出后端和 Voilà 不兼容。解决办法是在 notebook 开头执行%matplotlib inline把这行加进去之后matplotlib 的图表就会以内嵌形式输出Voilà 也能正常展示。如果你用了 seaborn它其实底层还是 matplotlib所以%matplotlib inline同样适用。另一个原因是代码单元格里用了plt.show()这本身没问题但有些版本的 Voilà 对动态输出的刷新有延迟。建议把plt.show()放在单元格最后不要和大量 print 语句混在一起避免渲染时的优先级冲突。6.4 pip 安装时的依赖冲突处理建议装了 JupyterLab 之后再装其他数据分析库时偶尔会提示依赖冲突。这种情况下我一般不建议强拆强装。优先做法是用虚拟环境隔离或直接改用 conda 环境。Conda 的依赖解析器比 pip 强不少它能自动帮你挑一套互不冲突的包版本。如果你已经在 conda 环境里可以执行conda install jupyterlab notebook voilaConda 会尝试找到兼容的组合。实在冲突且无法解决时再手动指定版本安装。比如pip install voila0.5.0这种手动锁版本的方式会让环境更可控但也意味着后续升级时可能还有冲突所以我始终强调环境隔离优先于强行统一版本。6.5 Windows 用户特有的坑编码与路径问题Windows 上使用 Jupyter 时我遇到最多的是路径编码问题。如果你的用户名或项目路径包含中文有些库在读写文件时可能报 UnicodeDecodeError 或 FileNotFoundError。这个问题在 Jupyter 自身处理得还行但在某些扩展库尤其是老版本 Pandas身上比较明显。我的建议是项目目录尽量用英文文件名也尽量不用中文。这不是什么高科技但确实能省掉很多莫名其妙的报错。如果你接手了一个已存在中文路径的项目可以在 notebook 开头设置import sys import io sys.stdout io.TextIOWrapper(sys.stdout.buffer, encodingutf-8)这样可以缓解一部分中文编码问题但最好的解决方案还是从源头规避。7. 扩展配置token、密码、远程访问与常用插件7.1 登录安全配置token 与密码JupyterLab 和 Notebook 默认启动时会生成一个 tokenURL 里会显示。这个 token 相当于你访问服务的凭证。如果你觉得每次复制 URL 带 token 太麻烦可以设置固定密码。最推荐的方式还是在终端里执行jupyter server password输入两遍密码后它会自动写入配置文件~/.jupyter/jupyter_server_config.json。之后启动 JupyterLab 访问时就可以用这个密码登录而不需要 URL 里带 token。如果你想手动配置自定义端口、IP、是否允许远程访问可以生成配置文件再修改jupyter server --generate-config生成的文件位于~/.jupyter/jupyter_server_config.py。打开后找到对应的配置项修改即可。常用配置通常包括c.ServerApp.ip 0.0.0.0 c.ServerApp.port 8888 c.ServerApp.open_browser False c.ServerApp.allow_remote_access True这里我提醒一下allow_remote_access True意味着可以从外部访问如果是在敏感网络或公网环境一定要配上密码并且最好用防火墙把端口限定在内网可访问。7.2 常用插件我实际在用的几款JupyterLab 的扩展机制让它比 Notebook 更灵活。插件安装方式很简单在 JupyterLab 界面里进入 Extension Manager搜索插件名称点 Install 即可。我实际用下来觉得值得装的插件有这些Table of Contents自动生成 notebook 标题目录长文档导航神器。jupyterlab-git在界面里直接进行 Git 操作查看 diff、提交和推送方便到不用开命令行。jupyterlab-spreadsheet在 JupyterLab 里直接预览 CSV 文件双击就能看到表格不用每次都用 pandas 读一遍。jupyterlab/toc左侧目录树配合长 notebook 使用体验极佳。jupyterlab-variableinspector边写代码边看当前环境里所有变量的值调试时会省很多事。Notebook 那边也有不少经典扩展比如 nbextensions 里的 Table of Contents、Collapsible Headings、Codefolding。但这些插件的安装方式使用 pip 安装jupyter_contrib_nbextensions后启用比较折腾而且和 JupyterLab 的扩展机制完全不同。所以我建议新用户直接拥抱 JupyterLab 的扩展生态即可不必再花时间折腾老插件。7.3 远程访问与反向代理更优雅的部署方式如果你在云服务器上使用 Jupyter 生态除了直接在公网监听端口之外我更推荐的部署方式是用反向代理。以 nginx 为例可以这样配置一个子路径代理location /jupyter/ { proxy_pass http://127.0.0.1:8888/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; }注意 JupyterLab 使用 WebSocket 进行实时通信所以必须配置Upgrade和Connection头否则前端可能出现connection closed的报错。这种部署的好处是你可以通过https://域名/jupyter/统一入口访问并且可以在 nginx 层做访问控制、配置 SSL、把多个服务如 JupyterLab 和 Voilà映射到不同路径管理起来更规范。如果你前面已经设置了 Jupyter 密码外部访问的安全性就有了双重保障。8. 从 notebook 迁移到 JupyterLab我给你的平滑转型建议8.1 别着急切环境先从混用开始不少朋友问我要不要把手头所有 Notebook 项目都迁到 JupyterLab我的回答是不用着急先从混用开始。JupyterLab 打开.ipynb文件完全兼容旧格式你直接拿 JupyterLab 打开原本在 Notebook 里写的文件代码和输出都会原样显示。早期你不需要做任何迁移工作只需要在日常操作中慢慢增加 JupyterLab 的使用比例新建的项目优先在 JupyterLab 里做只有打开旧的、依赖老插件的文件时才切回 Notebook。我还建议你把平时常用的命令记下来比如jupyter lab、jupyter notebook、jupyter server password、python -m ipykernel install以及voila。时间久了你会形成一种肌肉记忆需要开发环境时打开 JupyterLab需要快速测试时打开 Notebook需要分享交付时跑 Voilà。三者随时可以切换不存在只能选一个的问题。8.2 文件整理与目录结构的建议Jupyter 生态的项目目录最好一开始就规划好。我自己的典型结构是这样的project/ ├── data/ │ ├── raw/ │ └── processed/ ├── notebooks/ │ ├── 01_explore.ipynb │ ├── 02_model.ipynb │ └── dashboard.ipynb ├── scripts/ │ ├── preprocess.py │ └── utils.py ├── output/ │ ├── figures/ │ └── reports/ └── README.md这样的好处是Voilà 发布时只需要指定notebooks/dashboard.ipynb数据路径统一从data/读取不会出现代码在 notebook 里能跑在 Voilà 里找不到文件的悲剧。脚本和 notebook 分离也让项目更容易回溯和维护。8.3 备份与版本管理Jupyter notebook 文件是 JSON 格式每次保存都会生成一个快照。但多人协作或自己长期迭代时强烈建议用 Git 做版本管理。你可以在 JupyterLab 的终端里对项目目录执行git init然后配合前面提到的 jupyterlab-git 插件在界面里直接提交。这样每次改动都有历史随时可以回退。另外要提醒的是.ipynb文件里会保存执行输出输出里如果包含了大量图片会让 Git diff 变得非常难读。如果团队协作严格建议在 Git 客户端里启用nbstripout工具在提交前剥离输出只保留代码和 markdown能显著减小仓库体积也让代码审查更聚焦。我自己的习惯是本地保留完整输出提交到远程仓库时用nbstripout清理需要展示结果时再通过 Voilà 生成网页给最终受众。9. 个人使用体会与下一步可以尝试的方向如果让我用一个比喻来总结 JupyterLab、Notebook 和 Voilà 的关系Notebook 是厨房里的炒锅JupyterLab 是整间厨房Voilà 则是把做好的菜端到餐厅给客人品尝。这三件事在不同阶段出现解决的是不同层次的问题它们之间并不冲突反而是我目前见过的最有效率的数据工作流之一。最后分享一个我最近在尝试的方向把 Voilà 发布的应用和定时任务结合起来。比如用 cron 在每天凌晨自动跑数据更新脚本输出最新的分析结果到output/目录Voilà 每次打开时不重新计算而是读取已经刷新好的数据文件。这样一来团队每天打开应用看到的都是昨天的数据而服务器资源消耗几乎为零。如果你已经完成了本文里的安装和使用流程我很建议你往这个方向再走一步——它会让你的数据产品从能用进化到真正能持续运行。希望这篇东西对你的 Jupyter 之路有实实在在的帮助。遇到具体报错时优先回看环境隔离、内核选择、文件路径这几个最容易被忽视的环节多数问题都能在那里找到答案。
