callstackio先说个题外话：“jupyterlb”这个拼写，在搜索后台里出现的频率相当高。第一次看到的时候我也愣了一下，后来才意识到大家要找的其实是JupyterLab——字母顺序输错是常见的输入法事故。名字的问题放一边，关键是你找对了工具，所以接下来我会把JupyterLab从安装到启动的整个流程，用我在好几台机器上反复实践后确认靠谱的方式，完整讲一遍。
JupyterLab是目前Python数据分析、机器学习场景下最顺手的交互式开发环境之一，比老版Notebook的界面现代化很多，文件管理、终端、Markdown、代码运行能在同一个窗口里搞定，日常写脚本做分析基本不用切来切去。这篇文章就是一份从零跑到能用的实操档案，覆盖安装、启动、配置和典型坑点排查，适合刚入门的初学者，也适合换了新机器想快速搭建环境的老手。
1. 先搞清楚目标：JupyterLab是什么，能解决什么问题
1.1 它和Jupyter Notebook到底什么关系
很多人把JupyterLab和Jupyter Notebook当成两个完全独立的东西，实际上它们是同一家族的产品。Notebook是早期推出的网页交互式编程界面，一个ipynb文件对应一个页面，单元格里能写代码、能写Markdown、能跑出图表；JupyterLab是它的下一代界面，相当于把原来分散的多个Notebook页面整合成了一个类似IDE的工作台。
在JupyterLab里，你可以左侧打开文件树、中间编辑代码、右侧开着终端，拖拽窗口到任意位置，比老Notebook的线性布局灵活得多。同一个ipynb文件在JupyterLab里打开完全兼容，之前Notebook里建的项目直接可以用，不存在迁移成本。
1.2 为什么做数据相关工作基本绕不开它
原因其实很朴实：数据处理是一个反复试错的过程，你经常要写一小段代码、跑一下、看结果、改参数、再跑。JupyterLab把“代码—结果—可视化”放在同一个页面里，天然适合这种节奏。相比纯粹的IDE（如PyCharm、VS Code），它少了一些工程化配置的繁琐，起步更快；相比写一行跑一行的解释器，它又能保留每一步的中间结果，方便来回对照。
对于教学场景、数据分析报告、机器学习特征探索、快速原型验证这类工作，JupyterLab基本是首选工具。即使你平时主力写代码用的是VS Code或PyCharm，装一个JupyterLab也不会亏，很多临时性探索任务放到它里面做反而更顺手。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 安装前必须确定的三件事情，少做一件都是坑
2.1 Python版本：不是越新越好，也不是有就行
JupyterLab对Python版本有下限要求，装之前建议先确认一下。目前稳定版本要求Python 3.9及以上，太老的3.6、3.7装上之后部分依赖可能编译报错，或者功能残缺。
太新的Python版本有时也会遇到兼容问题，尤其当你机器上还有一堆旧包的时候。我的原则是：日常使用选3.9到3.12之间的稳定版本，别盲目追最新。装JupyterLab这种事不需要用最前沿版本冒险。
如果你还没装Python，可以分别从Python官网和Anaconda发行版两条路线里选一条。官方Python轻量，配合pip走天下；Anaconda自带一堆数据科学包，省心但体积大。
2.2 用pip还是用conda：先分清自己的使用场景
这是安装前必须想清楚的问题，因为选错包管理工具，后面会遇到不少莫名其妙的麻烦。
- 如果你已经在用Anaconda或Miniconda，建议直接用conda装JupyterLab，好处是conda会把依赖关系处理好，避免污染系统Python。
- 如果你用的是官方Python，或者你只是想在现有环境里快速加一个工具，那么pip install jupyterlab就够了。
- 如果你常用虚拟环境（venv或conda env），那在哪个环境里用JupyterLab，就在那个环境里安装它，不要一股脑装到base环境里。
pip和conda混用不是不行，但容易造成版本错乱。最典型的情况是：conda环境里已经有一版jupyter-core，再用pip装一版高版本jupyterlab，把依赖搞冲突，启动时报ModuleNotFoundError。我的建议是选定一个主力工具，别频繁切换。
2.3 虚拟环境：这次装完不想半年后翻车就看这节
虚拟环境的核心价值，说得直白点就是“隔离”。你在这个项目里用的JupyterLab、pandas、numpy是一套版本组合，另一个项目可能是完全不同的版本组合，如果不隔离，两个项目互相升级包，最终谁都跑不了。
以venv为例，创建和使用非常简单：
bash复制mkdir myproject && cd myproject
python -m venv .venv
source .venv/bin/activate # Windows下为 .venv\Scripts\activate
pip install jupyterlab
激活虚拟环境后，再执行jupyter-lab命令，启动的就是当前虚拟环境里装的版本。如果你在JupyterLab里新建Notebook后切换内核，也会看到不同虚拟环境对应的内核选项。
很多人一开始图省事，把所有东西都塞在全局环境里，半年后装新包时各种冲突，最后只能追悔莫及重装Python。所以这篇教程里我默认你至少会用一个虚拟环境，实际上强烈建议用。
3. 实操第一步：用pip安装JupyterLab的完整过程
3.1 确认Python和pip可用
在终端里先跑两条命令，确认基础环境没问题：
bash复制python --version
pip --version
如果提示找不到命令，说明Python没装好或者没加到系统PATH里。Windows用户遇到这个问题最多，安装Python时记得勾选“Add Python to PATH”选项，能省掉后面很多麻烦。
如果pip显示的是旧版本，可以顺手升级一下：
bash复制python -m pip install --upgrade pip
这一步不是必须的，但可以避免安装某些包时因为pip太旧而出现的协议或解析问题。
3.2 用pip安装JupyterLab
直接在终端执行：
bash复制pip install jupyterlab
正常情况下会下载一堆依赖包，终端滚屏几分钟后显示Successfully installed就完成了。过程中如果卡在Downloading很久不动，多半是网络问题，建议配置国内镜像源，例如清华源：
bash复制pip install jupyterlab -i https://pypi.tuna.tsinghua.edu.cn/simple
镜像源只是一个下载地址，不改变安装逻辑，换源之后速度快很多，但如果你的网络本身能正常访问官方源，不换也行。
3.3 验证安装是否成功
安装完成后，等几秒钟让pip完成收尾，然后执行：
bash复制jupyter-lab --version
如果输出了一个版本号，比如4.2.x，说明核心安装成功。这时候可以先不启动，因为标准安装后还需要看内核是否可用（也就是你的Python解释器能不能被JupyterLab调用）。
检查内核的方法：
bash复制jupyter kernelspec list
显示python3就说明内核基本正常。如果你用的是虚拟环境，但这里没看到当前环境的内核，需要执行：
bash复制python -m ipykernel install --user --name=myenv --display-name="Python (myenv)"
前提是当前虚拟环境里已经安装了ipykernel。没装的话可以先：pip install ipykernel。
4. 另一种主流安装方式：conda安装JupyterLab
4.1 为什么推荐conda用户直接用conda装
如果你已经装了Anaconda或Miniconda，再使用pip装JupyterLab，有时会把conda管理好的依赖环境搅乱。conda安装的好处在于它对依赖的处理方式更接近“二进制分发”，很多包不用现场编译，版本冲突概率更低。
另外conda自带多版本Python管理能力，用conda create -n py311 python=3.11就能快速建一个独立环境，再往里装JupyterLab，隔离效果比venv还直观。
4.2 conda安装的操作步骤和常见细节
先创建并激活环境：
bash复制conda create -n jupyter-env python=3.11 -y
conda activate jupyter-env
然后安装JupyterLab：
bash复制conda install -c conda-forge jupyterlab
conda-forge是社区维护的通道，包更新频率高，JupyterLab这类工具优先从它安装比较稳。安装过程同样需要等待依赖解析，速度取决于镜像源和网络。国内用户可以配置conda的清华镜像：
bash复制conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge
conda config --set show_channel_urls yes
配置完后再次执行conda install，下载速度会有明显提升。
这里有个细节需要注意：conda install jupyterlab默认装的版本可能不是最新版，因为conda的依赖库和pip的上游同步有延迟。如果你追求最新功能，可以用conda-forge通道指定版本。但我们日常使用不必追新，稳定优先。
5. 启动JupyterLab：从首次运行到日常启动技巧
5.1 第一次启动，先把这几个参数用熟
安装完成后的第一件事就是启动。在终端执行：
bash复制jupyter-lab
如果一切正常，终端会打印出几个访问地址，浏览器也会自动打开，默认地址是http://localhost:8888/lab。
第一次启动时JupyterLab会生成配置文件目录，同时要求你输入一个token。本地访问通常不用关心token，因为浏览器是自动跳转的；如果自动打开失败，你就需要手动复制终端里给出的完整URL，在浏览器里打开。
最常用的几个启动参数：
| 参数 | 作用 | 示例 |
|---|---|---|
| --port | 指定端口 | jupyter-lab --port=9999 |
| --no-browser | 不自动打开浏览器 | jupyter-lab --no-browser |
| --ip | 监听地址 | jupyter-lab --ip=0.0.0.0 |
| --NotebookApp.token='' | 关闭token验证 | jupyter-lab --NotebookApp.token='' |
比如你只想在后台启动JupyterLab，不想让它自动弹浏览器，可以这样：
bash复制jupyter-lab --no-browser --port=8888
然后自己在浏览器里手动打开指定地址。这个方式在远程服务器场景里特别常用。
5.2 配置文件：让JupyterLab记住你的偏好
每次启动都用一长串参数很痛苦，JupyterLab支持配置文件。生成默认配置：
bash复制jupyter-lab --generate-config
这会在你的用户目录下生成一个jupyter_notebook_config.py文件。打开它，你可以设置端口、IP、token、工作目录等。比如想固定工作目录到/home/user/work：
python复制c.ServerApp.root_dir = '/home/user/work'
修改完保存，以后直接执行jupyter-lab，它就会读取这些配置，不用每次敲参数。
新版本JupyterLab还支持在界面里直接设置部分偏好，比如主题、字号、自动保存间隔，这些偏好存储在你的用户配置文件里，不需要手改代码。
5.3 后台常驻启动和远程访问的配置
如果你有一台服务器，希望JupyterLab在断开SSH后继续运行，需要使用后台启动方式：
bash复制nohup jupyter-lab --no-browser --ip=0.0.0.0 --port=8888 > jupyter.log 2>&1 &
这样启动后，关闭SSH窗口JupyterLab不会退出，日志输出到jupyter.log文件，方便随时查看。
远程访问时，浏览器访问http://服务器IP:8888/lab。这里有一个安全要点：如果设置了token，访问时需要输入token；如果没设置token，等于任何人都能访问你的服务器文件，非常危险。建议设置一个强密码或者保留token，不要裸奔。
JupyterLab的密码设置：
bash复制jupyter-lab password
按提示输入两次密码即可。它会生成哈希值写入配置，之后远程登录就用这个密码，不再依赖随机token。
6. 安装和启动阶段最容易踩的5个坑
6.1 pip install卡在Downloading，解决方案
最常见的现象是执行pip install jupyterlab后，进度条纹丝不动，等了五分钟还在Downloading。原因通常是网络到官方源不稳定。
解决方案就是换镜像源，前面提到的清华源、阿里源都可以：
bash复制pip install jupyterlab -i https://pypi.tuna.tsinghua.edu.cn/simple
如果想永久生效，在用户目录下创建或修改pip.conf（Windows下是pip.ini），写入：
ini复制[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
之后所有pip命令都默认走镜像源。注意镜像源有时候同步会有延迟，刚发布的新版本在镜像源上可能晚几天才出现，但不影响日常使用。
6.2 输入jupyter-lab提示command not found
安装成功了，却提示命令找不到。这个问题的本质是脚本目录没有加入PATH。
pip安装的可执行脚本路径通常在：
- Linux/macOS：~/.local/bin 或 Python安装目录下的bin/
- Windows：Python安装目录下的Scripts/
解决方法是把对应路径加入系统PATH。Windows用户在系统环境变量里找Path，添加Scripts目录路径；Linux用户可以临时执行：
bash复制export PATH="$HOME/.local/bin:$PATH"
或写入~/.bashrc让配置永久生效。
另外，如果你用了conda但在base环境之外激活环境时命令找不到，通常是因为conda activate没有正确执行，检查一下终端提示符前面是否有环境名。
6.3 浏览器打开了但页面一直转圈
启动地址能访问，但页面一直加载中，常见的罪魁祸首是浏览器缓存或者JS资源加载问题。
最简单的解法是强制刷新：Ctrl+Shift+R（Windows/Linux）或者Cmd+Shift+R（Mac），让浏览器重新拉取静态资源。如果还不行，关掉JupyterLab进程，清理一下浏览器站点缓存，再重新启动。
另外，新版本的JupyterLab对本地浏览器版本有要求，太老的浏览器可能无法正常工作，建议升级到最新版Chrome或Firefox。
6.4 启动显示端口被占用
执行jupyter-lab时提示端口被占用，一般日志里会显示类似Address already in use的信息。这通常是因为之前启动的JupyterLab没有退出，或者其他服务占用了8888端口。
先查看占用端口的进程：
bash复制# Linux/macOS
lsof -i :8888
# Windows
netstat -ano | findstr :8888
找到PID后杀掉进程，或者换个端口启动：
bash复制jupyter-lab --port=8890
我更推荐换端口，因为杀进程有时候会误伤。
6.5 启动成功但访问不了，防火墙拦截
远程场景下JupyterLab已经在服务器上跑起来了，但本地浏览器访问超时。这种情况十有八九是防火墙拦截了端口。
Linux服务器上，执行：
bash复制sudo firewall-cmd --zone=public --add-port=8888/tcp --permanent
sudo firewall-cmd --reload
如果是腾讯云、阿里云这类云服务器，还要到云控制台的“安全组”里放行8888端口的入站规则。这个细节经常被人忽略，本机能访问、外部访问不了，排查头大。
之后再用http://服务器IP:8888/lab访问，大概率能通了。
7. 装好之后还能做点什么，让JupyterLab更像日常主力工具
安装启动只是第一步，真正把JupyterLab用顺手，还需要做一些小配置。
7.1 安装常用扩展插件
JupyterLab 4.x的扩展安装比老版本清爽，很多功能在界面左侧的“Extension Manager”里直接搜索安装，不用再像旧版那样npm装半天。
常用的几个：
- jupyterlab-git：提供Git管理界面，查看变更、提交都不用切终端
- jupyterlab-lsp：代码补全和诊断提示，写Python、R都会舒服很多
- jupyterlab-spellchecker：拼写检查，写Markdown笔记时有用
- jupyterlab-execute-time：显示每个单元格的执行时长，分析性能很有帮助
插件安装方式以pip为主，例如：
bash复制pip install jupyterlab-git jupyterlab-lsp jupyterlab-execute-time
装完记得重启JupyterLab，插件才会生效。
7.2 设置默认工作目录和主题
默认工作目录的设置前面提到过，在jupyter_notebook_config.py里改c.ServerApp.root_dir就行。如果你不想改全局配置，也可以在浏览器界面里右键文件夹选择“在终端中打开”来快速切换。
主题方面，JupyterLab内置了亮色和暗色主题，在Settings → Theme里切换。如果需要更多主题，可以装jupyterlab-theme扩展。
7.3 多内核管理：从一个入口用不同语言环境
JupyterLab不只能运行Python，还可以挂R、Julia、SQL甚至C++的内核。你只要在对应环境里安装对应的IPython内核，重启后就能在New Launcher里看到。
这是JupyterLab最让我舒服的一点：数据分析和实验很可能需要混用多种工具，它能在同一个入口下切换不同内核，不用来回开多个IDE。
8. 关于安装启动时机的选择：什么时候换新环境，什么时候直接用旧环境
有些读者可能会问：既然我已经有一个能跑的JupyterLab，还需要按这篇教程重新装吗？
我的建议是看看升级成本。如果你的旧环境是两年前的版本，中间积累了大量的包，直接pip install --upgrade jupyterlab可能会牵扯出很多依赖问题。这种情况下更推荐新开一个虚拟环境或conda环境，干净安装新版本，把旧环境当一个备用环境保留着，等确认新环境没问题再迁移。
如果你只是想在现有环境里小版本升级，比如从4.0升到4.2，直接：
bash复制pip install --upgrade jupyterlab
风险不大，但升级前最好先备份一下.ipynb和配置文件。
另外还有一种常见需求：机器上同时存在Python 3.8和3.11两套环境，想用JupyterLab统一管理。这种场景直接用conda创建两个环境，分别安装jupyterlab，再在其中一个环境里启动JupyterLab，就能在kernel菜单里看到另一个环境的内核（前提是安装了ipykernel）。
9. 聊几个实际操作中容易忽视的小细节
写代码跑通之后，很多人的注意力就全放在业务逻辑上了，但JupyterLab本身的维护细节其实也值得定期处理。
比如你长期打开着几十个文件标签，JupyterLab的界面会越来越卡。解决办法是定期关闭不用的标签页，或者直接重启JupyterLab，让前端资源重新加载。这个操作很多人嫌麻烦，但确实有效。
比如ipynb文件中途如果包含比较大的数据帧或者图表，保存的文件体积会很大，打开变得很慢。推荐在保存之前把不需要输出的单元格清空，或者用jupyter nbconvert --clear-output命令批量清理输出。
再比如JupyterLab的自动保存功能，默认是启用的，但如果你手动改过配置文件，要注意别把自动保存关了，否则断电丢代码的滋味不好受。
最后提醒一句：JupyterLab不是项目管理工具，它更适合探索和实验。等你的代码进入稳定阶段，该迁移到纯Python脚本还是尽早迁移，这样后期维护会省力很多。这也是我自己的工作流：JupyterLab里跑通逻辑，然后整理成py文件放进正式项目。
安装启动这件事本身不难，难的是搞清楚每个步骤背后的原因。希望这篇内容能帮你少走点弯路，也让JupyterLab真正成为日常开发的顺手工具。