Python安装Jupyter后怎么验证版本并启动服务
详细介绍在Python环境中安装Jupyter后,如何正确验证各个核心组件版本、如何启动Jupyter Notebook与JupyterLab服务、常见命令差异及连接排查技巧。
jupyter --version,而启动服务常用的命令是 jupyter notebook 或更现代的 jupyter lab。如果遇到命令未识别,可以直接用当前 Python 模块化调用 python -m jupyter notebook。本文梳理从版本输出识别、基础启动、关键参数调整到常见网络与环境异常的排查链路。
一、操作全流程概览
完成 pip install jupyter 或 pip install jupyterlab 后,完整的验证与启动过程包含四个连续阶段:确认执行环境、执行版本查询、拉起服务进程,以及在浏览器中基于安全 Token 完成握手连接。
图 1:Jupyter 安装后的全流程执行路径
二、验证安装:如何正确查看 Jupyter 版本
很多刚接触 Jupyter 的读者常常以为它像 Git 或 Python 一样,执行一个命令就会返回单一的版本数字(如 3.11.0)。但当你运行以下命令时,终端返回的通常是一个多行清单:
jupyter --version
终端输出示例
Selected Jupyter core packages...
IPython : 8.22.2
ipykernel : 6.29.3
ipywidgets : 8.1.2
jupyter_client : 8.6.1
jupyter_core : 5.7.2
jupyter_server : 2.13.0
jupyterlab : 4.1.5
nbclient : 0.10.0
nbconvert : 7.16.3
nbformat : 5.10.3
notebook : 7.1.2
qtconsole : not installed
traitlets : 5.14.2
为什么会输出多个组件的版本?
这是由 Jupyter 的架构决定的。在现代 Python 生态中,“Jupyter” 本质上是一个协同工作的软件套件集合,而不是一个单一可执行二进制文件。每个模块承担着明确的独立职责:
- jupyter_core 与 jupyter_client:负责文件路径查找、全局配置管理以及前端界面与计算内核之间的协议通信(基于 ZeroMQ)。
- IPython 与 ipykernel:实际执行 Python 代码的内核引擎。当你点击单元格运行一段代码时,真正执行计算并返回变量的是 ipykernel。
- jupyter_server:提供底层 Web 服务的轻量级 Python HTTP/WebSocket 服务器。
- notebook / jupyterlab:展现给用户的网页端前端应用界面。
图 2:Jupyter 生态组件分层与职责示意图
jupyter_core、jupyter_server 以及 ipykernel 均显示正常版本号,且至少拥有 notebook 或 jupyterlab 之一,就表明安装已经具备服务运行的基础。
三、启动服务:启动 Notebook 与 JupyterLab
完成验证后,可以根据安装的具体产品选择启动命令。
1. 启动经典模式(Jupyter Notebook)
在准备存放代码或项目的目录中打开终端,执行:
jupyter notebook
该命令会在当前前台启动一个 Web 服务。启动成功后,默认会调用系统的默认浏览器,并直接打开类似 http://localhost:8888/tree 的管理页面。
2. 启动现代工作台(JupyterLab)
如果你安装的是较新的 JupyterLab(推荐用于日常数据分析和开发),执行:
jupyter lab
JupyterLab 提供了文件浏览器、多窗口编辑、终端集成和实时 Markdown 预览等功能,是目前官方主推的交互式开发界面。
3. 服务启动背后的通信流程
很多初学者在执行启动命令后,不知道终端里打印的那一大串英文信息代表什么,甚至直接随手关掉了终端窗口导致网页断开。下图展示了从命令行到网页建立连接的时序过程:
图 3:Jupyter 服务启动、Token 验证与内核建立时序图
4. 常用启动参数与实际应用场景
在日常使用中,直接输入不带参数的命令并不总能满足所有场景,下表整理了最常用的控制选项:
| 参数 | 使用示例 | 适用场景与作用 |
|---|---|---|
--no-browser |
jupyter notebook --no-browser |
在服务器、远程终端或 SSH 链接中使用,禁止在本地自动唤起桌面浏览器。 |
--port <端口号> |
jupyter notebook --port 8899 |
当默认端口 8888 已被占满或需要同时运行多个不同配置的实例时指定。 |
--ip <地址> |
jupyter notebook --ip=0.0.0.0 |
允许局域网或外部机器访问(注意必须保留或妥善配置密码/Token)。 |
--notebook-dir <路径> |
jupyter notebook --notebook-dir=D:/Projects |
指定 Jupyter 启动后的根工作目录,不需要先通过 cd 切换目录。 |
四、容易混淆的关键认知与场景辨析
在实际操作中,读者最常遇到的两个卡点,往往不是安装失败,而是对运行环境和调用机制存在误解。
1. 误区一:“直接输入 jupyter 提示命令未找到,说明安装失败了”
实情辨析:这是初学者最容易产生误判的地方。在 Windows、macOS 或 Linux 上,通过 pip install jupyter 安装时,可执行脚本会被放在对应 Python 解释器的 Scripts(Windows)或 bin(macOS/Linux)目录下。如果这个路径未加入系统的全局环境变量(PATH),在终端直接敲 jupyter 就会提示:
- Windows:
'jupyter' 不是内部或外部命令,也不是可运行的程序 - macOS / Linux:
command not found: jupyter
这并不意味着包没有安装好,而是系统找不到对应的快捷命令。此时最有效且规范的解决方案是采用 Python 模块化语法直接调用:
python -m jupyter notebook
# 或者验证版本:
python -m jupyter --version
使用 python -m 会显式指定当前 Python 解释器去查找安装在其库目录中的 jupyter 模块,彻底绕过系统 PATH 环境变量的定位缺失问题,百分之百保证调用的是当前 Python 下的包。
2. 误区二:“在哪个终端启动 Jupyter,Notebook 里面运行的就是哪个 Python”
实情辨析:Jupyter 本身是一个服务端容器,而代码执行依赖的是“内核(Kernel)”。这两者是可以解耦的。启动 Jupyter 的 Python 环境负责维护网页服务,而 Notebook 页面右上角选择的 Kernel 才是真正运行代码的环境。
如果希望在特定的虚拟环境(例如 my_env)中运行代码,除了在该环境中启动 Jupyter 之外,还可以将该环境注册为一个独立的内核:
# 激活你的目标虚拟环境后执行:
python -m ipykernel install --user --name my_env --display-name "Python (my_env)"
这样即使你全局运行 Jupyter,也能在页面中随时切换到 my_env 执行计算,不需要频繁退出和重启服务。
五、启动后的状态确认与常见异常排查
当服务启动后,终端控制台会持续输出服务日志。可以通过以下特征判断服务是否真正健康可用:
图 4:常见故障现象与对应解决路径导图
终端正常输出的 Token 日志示例
当服务成功启动时,终端会打印如下形式的访问链接:
[I 10:15:20.124 ServerApp] Serving notebooks from local directory: /Users/username/workspace
[I 10:15:20.124 ServerApp] Jupyter Server 2.13.0 is running at:
[I 10:15:20.124 ServerApp] http://localhost:8888/tree?token=4a7d32c918bb40f80e0c8d19760c6dbe5b67ad2a23e19864
[I 10:15:20.124 ServerApp] http://127.0.0.1:8888/tree?token=4a7d32c918bb40f80e0c8d19760c6dbe5b67ad2a23e19864
[I 10:15:20.124 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
其中 token=... 后面的字符是保证本地安全的临时令牌。如果在浏览器中直接访问 http://localhost:8888 被要求输入密码,只需将终端中带有 token= 的完整链接复制到浏览器回车即可直接进入工作界面。
如何正确停止服务
如果需要结束 Jupyter 服务,请回到运行着该服务的终端窗口,按下键盘的快捷键:
Ctrl + C
终端会提示 Shutdown this Jupyter server (y/[n])?,输入 y 并回车(或者快速连按两次 Ctrl + C),服务即可平稳关闭并释放对应的端口资源。
六、常用命令速查总结
最后,将核心命令汇总以便快速参考:
- 验证版本(快捷命令):
jupyter --version - 验证版本(绝对可靠方式):
python -m jupyter --version - 启动经典笔记本:
jupyter notebook(或python -m jupyter notebook) - 启动现代实验室工作台:
jupyter lab(或python -m jupyterlab) - 指定目录与端口启动:
jupyter notebook --port 8890 --notebook-dir="/path/to/work" - 关闭后台运行的服务:在对应的终端界面按下
Ctrl + C
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









