JupyterLab 安装与启动完全指南

Name

Soren Atelier

Updated on 2026/2/13

搭建一个用于数据科学的 Python 开发环境本应很简单，但新手用户经常会遇到各种障碍：包管理器冲突、PATH 变量配置错误、权限问题，以及散落在过时论坛帖子中的各种令人困惑的建议。一个配置错误的安装可能让你在写出第一行代码之前就浪费数小时。

当 Jupyter 命令静默失败、kernel 拒绝连接或者浏览器始终无法打开时，这种挫败感会成倍增加。即使是经验丰富的开发者在更换电脑或配置远程服务器时也会遇到问题。没有一份清晰的参考指南，让 JupyterLab 正常运行的过程就会比实际需要的困难得多。

本指南将解决这些问题。它涵盖了如何使用 pip 和 conda 安装 JupyterLab，如何在各主流操作系统上启动 JupyterLab，以及如何配置它以提高工作效率。无论你是第一次打开 JupyterLab 还是在排查已损坏的安装，按照以下步骤操作，几分钟内你就能拥有一个可用的环境。

什么是 JupyterLab？

JupyterLab 是 Project Jupyter 推出的新一代基于 Web 的交互式开发环境。它用一个模块化、可扩展的工作空间取代了经典的 Jupyter Notebook 界面，你可以在单个浏览器窗口中编辑 notebook、编写脚本、使用终端、浏览文件和查看数据输出。

JupyterLab 的主要特性包括：

• 多面板布局：通过拖放排列，可以并排打开 notebook、终端、CSV 预览和文档。
• 内置文件浏览器：无需离开界面即可浏览项目目录、创建文件夹、上传文件和重命名资源。
• 集成终端：直接在 JupyterLab 内部运行 shell 命令，无需切换到外部终端。
• 富文本编辑：支持 Markdown 文件实时预览编辑，可以处理 JSON 文件，并原生查看图片。
• 扩展系统：通过 pip 可安装的扩展添加 Git 集成、代码格式化、语言服务器支持和自定义主题等功能。
• 多 kernel 支持：在同一工作空间中运行 Python、R、Julia 和其他语言的 kernel。

JupyterLab 是现代 Jupyter 安装中默认附带的界面。当你运行 jupyter lab 时，它会启动 JupyterLab 界面。它是 2026 年数据科学、机器学习、科学计算和交互式 Python 开发的推荐环境。

JupyterLab 与 Jupyter Notebook 对比

许多用户想知道应该使用 JupyterLab 还是经典的 Jupyter Notebook。简短的回答是：JupyterLab 是现代的继任者。Jupyter 团队已将 JupyterLab 指定为未来的主要界面，而 Jupyter Notebook 7 现在也共享相同的底层技术（JupyterLab 组件）。

以下是直接对比：

何时选择 JupyterLab：适用于任何新项目。它提供了 Jupyter Notebook 的所有功能，外加更强大的工作空间。如果你需要处理多个文件、使用终端或想要扩展功能，JupyterLab 是明确的选择。

何时继续使用 Notebook：如果你正在运行仅支持经典 Notebook 界面的旧版工具，或者你需要用最简单的 UI 来教授入门编程课程。

如何安装 JupyterLab

在安装 JupyterLab 之前，你需要 Python 3.8 或更高版本以及一个包管理器（pip 或 conda）。以下章节涵盖了所有常见的安装方式。

使用 pip 安装 JupyterLab（推荐）

pip 是默认的 Python 包管理器，也是安装 JupyterLab 最快的方式。打开终端（Windows 上的命令提示符或 PowerShell，macOS/Linux 上的终端）并运行：

pip install jupyterlab

此命令会下载并安装最新稳定版的 JupyterLab 及其所有必需的依赖项。要验证安装：

jupyter lab --version

你应该看到类似 4.3.x 或更高版本的输出。如果 pip 无法识别，你可能需要使用 pip3：

pip3 install jupyterlab

要将现有的 JupyterLab 安装升级到最新版本：

pip install --upgrade jupyterlab

使用 Conda 安装 JupyterLab（Anaconda/Miniconda）

如果你使用 Anaconda 或 Miniconda 进行包管理，可以从 conda-forge 频道安装 JupyterLab：

conda install -c conda-forge jupyterlab

这种方式在数据科学家中很流行，因为 conda 同时管理 Python 包和非 Python 依赖项（如某些科学计算包所需的 C 库）。

要在专用的 conda 环境中安装 JupyterLab：

conda create --name jupyter-env python=3.12
conda activate jupyter-env
conda install -c conda-forge jupyterlab

验证安装：

jupyter lab --version

Windows 安装步骤详解

按照以下步骤从零开始在 Windows 上安装 JupyterLab：

第 1 步：安装 Python

从 python.org/downloads (opens in a new tab) 下载最新的 Python 安装程序。安装过程中，务必勾选 "Add Python to PATH" 选项——这一步至关重要。没有它，python 和 pip 命令将无法在终端中使用。

第 2 步：打开终端

按 Win + R，输入 cmd，然后按回车。或者在开始菜单中搜索"PowerShell"。

第 3 步：验证 Python 和 pip

python --version
pip --version

两个命令都应该返回版本号。如果 python 无法识别，请重新安装 Python 并启用 PATH 选项。

第 4 步：安装 JupyterLab

pip install jupyterlab

第 5 步：启动 JupyterLab

jupyter lab

你的默认浏览器将自动打开 JupyterLab 界面。

macOS 安装

大多数版本的 macOS 自带 Python，但系统自带的 Python 版本通常较旧。建议使用 Homebrew 或 pyenv 进行干净的安装。

方式 A：使用 Homebrew

brew install python
pip3 install jupyterlab

方式 B：使用官方安装程序

从 python.org/downloads (opens in a new tab) 下载 Python 并运行 .pkg 安装程序。然后：

pip3 install jupyterlab

方式 C：使用 pyenv

brew install pyenv
pyenv install 3.12
pyenv global 3.12
pip install jupyterlab

启动 JupyterLab：

jupyter lab

Linux（Ubuntu/Debian）安装

大多数 Linux 发行版默认包含 Python 3。安装 pip 和 JupyterLab：

sudo apt update
sudo apt install python3 python3-pip python3-venv
pip3 install jupyterlab

在 Fedora/RHEL 上：

sudo dnf install python3 python3-pip
pip3 install jupyterlab

在 Arch Linux 上：

sudo pacman -S python python-pip
pip install jupyterlab

如果你的发行版在系统级别限制了 pip 安装（PEP 668），请先创建虚拟环境：

python3 -m venv ~/jupyter-env
source ~/jupyter-env/bin/activate
pip install jupyterlab
jupyter lab

如何启动 JupyterLab

JupyterLab 安装完成后，只需一个命令即可启动。本节涵盖了所有启动和配置 JupyterLab 的方式。

基本启动

打开终端并运行：

jupyter lab

JupyterLab 启动本地 Web 服务器（通常在端口 8888 上）并在默认浏览器中打开界面。终端会显示一个带有认证令牌的 URL：

http://localhost:8888/lab?token=abc123...

工作期间请保持终端窗口打开。关闭终端会停止 JupyterLab 服务器。

在指定目录中启动 JupyterLab

默认情况下，JupyterLab 在你运行命令的目录中打开。要在特定的项目文件夹中启动：

jupyter lab --notebook-dir=/path/to/your/project

在 Windows 上：

jupyter lab --notebook-dir=C:\Users\YourName\Projects\data-analysis

当你想让 JupyterLab 文件浏览器聚焦于特定项目时，这非常有用。

使用自定义端口

如果端口 8888 已被占用，可以指定其他端口：

jupyter lab --port=9999

此时 JupyterLab 将在 http://localhost:9999/lab 上可用。

启动时不打开浏览器

启动服务器但不自动打开浏览器窗口：

jupyter lab --no-browser

这在远程服务器上或你想手动导航到 URL 时非常有用。从终端输出中复制 URL 并粘贴到任何浏览器中即可。

在指定浏览器中打开 JupyterLab

强制 JupyterLab 在特定浏览器中打开：

jupyter lab --browser=firefox

或

jupyter lab --browser=chrome

在所有网络接口上启动 JupyterLab

要从同一网络上的其他设备访问 JupyterLab（例如远程服务器）：

jupyter lab --ip=0.0.0.0 --port=8888 --no-browser

然后使用服务器的 IP 地址从其他机器连接。

启动命令汇总

如何使用 JupyterLab

打开 JupyterLab 后，界面会显示一个启动器标签页，其中包含创建新 notebook、打开控制台、启动终端或创建文本文件的选项。本节涵盖基本工作流程。

创建和运行 Notebook

1. 在启动器的"Notebook"部分点击 Python 3，或通过 File > New > Notebook。
2. 出现提示时选择一个 kernel（通常是"Python 3"）。
3. 一个新的 .ipynb notebook 打开，包含一个空的代码单元格。

在单元格中输入 Python 代码，然后按 Shift + Enter 执行。输出直接显示在单元格下方。

import pandas as pd
import numpy as np
 
df = pd.DataFrame({
    'Name': ['Alice', 'Bob', 'Charlie'],
    'Score': [85, 92, 78]
})
df

使用单元格

JupyterLab notebook 使用两种主要的单元格类型：

代码单元格：执行 Python（或其他 kernel 语言）代码。结果内联显示。

Markdown 单元格：使用 Markdown 语法编写格式化文本。可以使用工具栏中的下拉菜单更改单元格类型，或在命令模式下按 M。

要添加新单元格，点击工具栏中的 + 按钮，或在命令模式下按 B（在下方）或 A（在上方）。在命令模式下按两次 D 删除单元格。

键盘快捷键

JupyterLab 有两种模式：命令模式（按 Escape，蓝色单元格边框）和编辑模式（按 Enter，绿色单元格边框）。以下是最常用的键盘快捷键：

你可以通过 Settings > Advanced Settings Editor > Keyboard Shortcuts 自定义键盘快捷键。

使用文件浏览器

左侧边栏包含一个文件浏览器，显示 JupyterLab 启动目录的内容。你可以：

• 点击导航文件夹
• 通过右键菜单创建新文件和文件夹
• 将文件拖放到浏览器中进行上传
• 右键 > 重命名来重命名文件
• 右键 > 删除来删除文件

内置终端

要在 JupyterLab 内部打开终端，转到 File > New > Terminal 或在启动器中点击 Terminal。这会提供一个完整的 shell（bash、zsh 或 PowerShell，取决于你的操作系统），无需离开 JupyterLab 界面。

集成终端适用于：

• 使用 pip 或 conda 安装包
• 运行脚本
• 使用 Git 命令
• 管理文件

多面板和分屏视图

JupyterLab 支持分屏工作流。将任何标签（notebook、终端、文件）拖到工作空间的边缘，即可创建并排布局。你可以水平或垂直排列面板。

常见的分屏设置：

• Notebook + 终端：在 notebook 中编写代码，同时在终端中运行命令
• 两个 Notebook：并排比较结果
• Notebook + CSV 预览：编码时查看数据文件
• Notebook + Markdown 预览：编写文档并实时预览

JupyterLab 故障排除

以下是用户在尝试运行 JupyterLab 时最常遇到的问题及其解决方案。

"jupyter: command not found"

这意味着 jupyter 可执行文件不在你的系统 PATH 中。常见解决方法：

检查 JupyterLab 是否已安装：

pip show jupyterlab

如果没有输出，请安装它：

pip install jupyterlab

使用完整的 Python 模块路径：

python -m jupyter lab

将 pip 的脚本目录添加到 PATH（Linux/macOS 上常见）：

export PATH="$HOME/.local/bin:$PATH"

将此行添加到你的 ~/.bashrc 或 ~/.zshrc 文件中使其永久生效。

Windows：如果安装 Python 时没有勾选"Add to PATH"，请重新安装 Python 并启用该选项，或手动将 C:\Users\YourName\AppData\Local\Programs\Python\Python312\Scripts 添加到系统 PATH 中。

端口已被占用

如果你看到"OSError: [Errno 98] Address already in use"：

jupyter lab --port=8889

或者找到并停止现有的 Jupyter 进程：

jupyter lab list
jupyter lab stop 8888

在 Linux/macOS 上，你还可以查找使用该端口的进程：

lsof -i :8888
kill -9 <PID>

权限错误

如果 pip install 因权限错误而失败，避免使用 sudo pip install。改用 --user 标志：

pip install --user jupyterlab

或者更好的做法是使用虚拟环境（详见下文）。

找不到 Kernel

如果你的 notebook 显示"Kernel not found"或 Python kernel 缺失：

pip install ipykernel
python -m ipykernel install --user

对于虚拟环境中的 kernel：

python -m ipykernel install --user --name=myenv --display-name="Python (myenv)"

JupyterLab 无法在浏览器中打开

如果服务器启动了但没有浏览器窗口出现：

1. 从终端输出中复制 URL（包括令牌）。
2. 直接粘贴到浏览器中。
3. 如果在远程服务器上运行，使用 SSH 端口转发：

ssh -L 8888:localhost:8888 user@remote-server

然后在本地机器上打开 http://localhost:8888/lab。

JupyterLab 显示空白页面

清除浏览器缓存或尝试使用其他浏览器。你也可以重置 JupyterLab 的工作空间：

jupyter lab --LabApp.default_url='/lab?reset'

JupyterLab 扩展

JupyterLab 4.x 使用简化的扩展系统，大多数扩展通过 pip 安装，无需 Node.js。以下是数据科学工作中最有用的扩展。

jupyterlab-git

JupyterLab 内完整的 Git 集成。可以查看差异、暂存更改、提交、推送和拉取，无需离开界面。

pip install jupyterlab-git

安装后，左侧边栏会出现一个 Git 标签。

jupyterlab-lsp

语言服务器协议支持，为 Python 和其他语言添加自动补全、悬停文档、跳转到定义和代码检查功能。

pip install jupyterlab-lsp python-lsp-server[all]

jupyterlab_code_formatter

使用 black 或 isort 等格式化工具自动格式化代码单元格。

pip install jupyterlab-code-formatter black isort

安装后，可通过工具栏按钮或键盘快捷键格式化单元格。

主题扩展

自定义 JupyterLab 外观：

pip install jupyterlab_darkside_ui    # 深色主题
pip install jupyterlab-night          # 夜间主题

通过 Settings > Theme 切换主题。

管理扩展

列出所有已安装的扩展：

jupyter labextension list

卸载扩展：

pip uninstall jupyterlab-git

增强数据可视化体验：PyGWalker

JupyterLab 是编写和运行代码的强大环境，但交互式数据可视化通常需要编写大量重复的绑图代码。PyGWalker 是一个开源 Python 库，可以将任何 pandas 或 polars DataFrame 转换为类似 Tableau 的交互式可视化界面，直接在 JupyterLab 内使用。

无需为每个图表编写 matplotlib 或 seaborn 代码，你可以通过拖放方式可视化探索数据：

pip install pygwalker

import pygwalker as pyg
import pandas as pd
 
df = pd.read_csv("your_data.csv")
pyg.walk(df)

这一个命令就能渲染出一个交互式 UI，你可以创建柱状图、散点图、直方图、热力图等，无需编写绑图代码。它支持筛选、聚合和多种图表类型——非常适合在 JupyterLab 中进行探索性数据分析。

了解更多请访问 github.com/Kanaries/pygwalker (opens in a new tab)。

如果你想在 Jupyter 中进一步使用 AI 驱动的自动化，可以试试 RunCell（www.runcell.dev (opens in a new tab)）——这是一个运行在 Jupyter 内部的 AI 代理，可以自动化 notebook 中的重复性任务，如数据清洗、特征工程和可视化。它能理解你的数据上下文，并为你生成代码单元格。

在虚拟环境中设置 JupyterLab

在虚拟环境中运行 JupyterLab 是推荐的做法。它可以隔离项目依赖，避免与其他 Python 安装产生冲突。

使用 Python venv

# Create a virtual environment
python -m venv jupyter-env
 
# Activate it
# macOS/Linux:
source jupyter-env/bin/activate
# Windows:
jupyter-env\Scripts\activate
 
# Install JupyterLab
pip install jupyterlab
 
# Start JupyterLab
jupyter lab

工作完成后，停用环境：

deactivate

使用 virtualenv

pip install virtualenv
virtualenv jupyter-env
source jupyter-env/bin/activate   # macOS/Linux
pip install jupyterlab
jupyter lab

使用 Conda 环境

conda create --name jupyter-env python=3.12
conda activate jupyter-env
conda install -c conda-forge jupyterlab
jupyter lab

将虚拟环境注册为 Kernel

如果你全局安装了 JupyterLab，但想使用虚拟环境中的包，可以将该环境注册为 kernel：

# Inside the activated virtual environment:
pip install ipykernel
python -m ipykernel install --user --name=jupyter-env --display-name="Python (jupyter-env)"

现在在 JupyterLab 中创建新 notebook 时，你可以选择"Python (jupyter-env)"作为 kernel。

使用 Docker 运行 JupyterLab

Docker 提供了一种干净、可复现的方式来运行 JupyterLab，无需在宿主系统上安装任何东西。Jupyter 项目维护着官方的 Docker 镜像。

快速开始

docker run -p 8888:8888 jupyter/base-notebook

这会拉取并运行基础 Jupyter 镜像。终端输出包含一个带有令牌的 URL。在浏览器中打开该 URL 即可。

挂载本地目录

要在容器内访问本地文件：

docker run -p 8888:8888 -v /path/to/your/project:/home/jovyan/work jupyter/base-notebook

在 Windows 上：

docker run -p 8888:8888 -v C:\Users\YourName\project:/home/jovyan/work jupyter/base-notebook

可用的 Docker 镜像

自定义 Dockerfile

为项目创建专用的 JupyterLab 环境 Dockerfile：

FROM jupyter/scipy-notebook:latest
 
# Install additional packages
RUN pip install pygwalker seaborn scikit-learn
 
# Set the working directory
WORKDIR /home/jovyan/work
 
# Expose the Jupyter port
EXPOSE 8888
 
CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root"]

构建并运行：

docker build -t my-jupyter .
docker run -p 8888:8888 -v $(pwd):/home/jovyan/work my-jupyter

Docker Compose

对于将 JupyterLab 与其他服务（数据库、API）组合使用的项目：

version: '3'
services:
  jupyter:
    image: jupyter/scipy-notebook
    ports:
      - "8888:8888"
    volumes:
      - ./notebooks:/home/jovyan/work
    environment:
      - JUPYTER_ENABLE_LAB=yes

docker compose up

管理多个 Python Kernel

当你在多个项目中使用不同的 Python 版本或包集时，可以将每个环境注册为 JupyterLab 中的独立 kernel。

从虚拟环境添加 Kernel

# Create and activate a new environment
python -m venv ml-project
source ml-project/bin/activate    # macOS/Linux
ml-project\Scripts\activate       # Windows
 
# Install the required packages
pip install ipykernel numpy pandas scikit-learn
 
# Register this environment as a Jupyter kernel
python -m ipykernel install --user --name=ml-project --display-name="Python (ML Project)"

从 Conda 环境添加 Kernel

conda create --name data-analysis python=3.11 pandas matplotlib
conda activate data-analysis
conda install ipykernel
python -m ipykernel install --user --name=data-analysis --display-name="Python (Data Analysis)"

列出已安装的 Kernel

jupyter kernelspec list

删除 Kernel

jupyter kernelspec remove ml-project

在 Notebook 中切换 Kernel

在打开的 notebook 中，点击右上角的 kernel 名称（例如"Python 3"），然后从下拉菜单中选择其他 kernel。你也可以通过菜单栏中的 Kernel > Change Kernel 进行切换。

常见问题

如何启动 JupyterLab？

打开终端并运行 jupyter lab。JupyterLab 服务器启动后，默认浏览器会自动打开。要在指定文件夹中启动，使用 jupyter lab --notebook-dir=/path/to/folder。

如何使用 pip 安装 JupyterLab？

在终端中运行 pip install jupyterlab。在 pip 指向 Python 2 的系统上使用 pip3。使用 jupyter lab --version 验证安装。

如何使用 conda 安装 JupyterLab？

运行 conda install -c conda-forge jupyterlab。为获得干净的设置，建议先创建专用的 conda 环境。

JupyterLab 和 Jupyter Notebook 有什么区别？

JupyterLab 是新一代界面，具有多面板布局、内置终端、文件浏览器和扩展功能。Jupyter Notebook 是原始的单文档界面。新项目推荐使用 JupyterLab。

如何解决"jupyter: command not found"？

使用 pip show jupyterlab 验证安装。如果已安装，尝试 python -m jupyter lab。否则，将 pip 脚本目录添加到系统 PATH 中。

如何在虚拟环境中运行 JupyterLab？

使用 python -m venv myenv 创建虚拟环境，激活它，使用 pip install jupyterlab 安装 JupyterLab，然后运行 jupyter lab。

如何使用 Docker 运行 JupyterLab？

运行 docker run -p 8888:8888 jupyter/base-notebook。使用 -v 标志挂载本地文件以实现持久化存储。

如何在不同端口上打开 JupyterLab？

使用 jupyter lab --port=9999 在端口 9999 上启动，而不是默认的 8888。

总结

JupyterLab 是 Python 数据科学、机器学习和科学计算的标准交互式开发环境。本指南涵盖了从安装到高级配置的每一步：

• 安装 JupyterLab：使用 pip install jupyterlab 或 conda install -c conda-forge jupyterlab
• 启动 JupyterLab：使用 jupyter lab 并通过端口、目录和浏览器标志自定义启动方式
• 高效使用 JupyterLab：利用键盘快捷键、分屏视图和集成终端
• 故障排除：解决命令未找到、端口冲突和 kernel 错误等常见问题
• 扩展功能：通过 Git 集成、LSP 支持和代码格式化增强 JupyterLab
• 环境隔离：使用虚拟环境和 Docker 实现可复现的工作流

无论你是首次接触 Python 的用户还是在新机器上配置环境的资深数据科学家，这些步骤都能帮你获得一个完整可用的 JupyterLab 环境。如需在 JupyterLab 中进行交互式数据可视化，试试 PyGWalker (opens in a new tab)，它可以将任何 DataFrame 变成拖放式可视化分析工具。