Chapter 02 / 10

安装与启动

pip、conda、venv 三种安装方式，以及如何配置工作目录、端口和远程访问

安装前提：Python 环境

Jupyter Notebook 需要 Python 3.8+。推荐使用虚拟环境隔离项目依赖：

# 检查 Python 版本（需要 3.8+）
$ python3 --version
Python 3.12.2

# 创建虚拟环境
$ python3 -m venv myenv

# 激活虚拟环境
$ source myenv/bin/activate      # macOS / Linux
$ myenv\Scripts\activate         # Windows

方法一：pip 安装（推荐）

最简单的安装方式：

# 安装 classic Jupyter Notebook
$ pip install notebook

# 或者安装功能更强大的 JupyterLab（现代推荐）
$ pip install jupyterlab

# 验证安装
$ jupyter --version
Selected Jupyter core packages...
IPython          : 9.5.0
ipykernel        : 7.2.0
jupyter_client   : 8.8.0
notebook         : 7.3.x
TIP notebook 是经典版（本教程主要介绍），jupyterlab 是下一代界面，两者可以同时安装。启动时分别用 jupyter notebook 和 jupyter lab。

方法二：conda 安装

如果你使用 Anaconda 或 Miniconda 管理 Python 环境，Jupyter 已经内置：

# Anaconda 发行版已预装 Jupyter，直接启动即可
$ conda list jupyter

# 用 conda 安装/更新
$ conda install -c conda-forge notebook jupyterlab

# 创建独立环境
$ conda create -n ds_env python=3.12 notebook pandas matplotlib
$ conda activate ds_env

安装常用科学计算包

数据科学工作通常需要以下套件：

$ pip install numpy pandas matplotlib seaborn scikit-learn
包名用途
numpy数值计算、多维数组
pandas数据框（DataFrame）、数据清洗
matplotlib2D 图表绘制
seaborn统计图表（基于 matplotlib）
scikit-learn机器学习算法库
scipy科学计算（积分、优化、统计）
ipywidgets交互式控件

启动 Jupyter Notebook

# 在当前目录启动
$ jupyter notebook

# 指定工作目录
$ jupyter notebook --notebook-dir=/Users/mi/projects

# 指定端口（默认 8888）
$ jupyter notebook --port=8889

# 不自动打开浏览器
$ jupyter notebook --no-browser

启动后，终端会输出类似：

To access the notebook, open this file in a browser:
    file:///Users/mi/.local/share/jupyter/runtime/nbserver-xxx.html
Or copy and paste one of these URLs:
    http://localhost:8888/?token=abc123def456...

浏览器会自动打开 http://localhost:8888/tree，显示 Jupyter 主页。

首次访问：Token 认证

Jupyter 默认开启 Token 认证，防止未授权访问。第一次打开时需要输入 Token：

WARNING 不要在公共网络上设置空 Token（--NotebookApp.token=''），这会让任何能访问该端口的人都可以执行代码。仅在本机开发时可以关闭认证。

配置文件

使用配置文件持久化设置，避免每次都要敲参数：

# 生成配置文件
$ jupyter notebook --generate-config
Writing default config to: /Users/mi/.jupyter/jupyter_notebook_config.py

# 编辑配置文件，修改以下选项：
# ~/.jupyter/jupyter_notebook_config.py

# 设置默认工作目录
c.NotebookApp.notebook_dir = '/Users/mi/notebooks'

# 设置端口
c.NotebookApp.port = 8888

# 关闭自动打开浏览器
c.NotebookApp.open_browser = False

# 设置密码（哈希值，用 jupyter notebook password 生成）
c.NotebookApp.password = 'argon2:...'

停止 Jupyter

在终端按 Ctrl+C，会提示：

Shutdown this notebook server (y/[n])? y

输入 y 确认停止。也可以在 Jupyter 主页的 File 菜单中选择 "Shut Down"。

国内加速安装

如果 pip 下载速度慢，可使用国内镜像：

# 使用清华镜像
$ pip install notebook -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或者设置为默认镜像
$ pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

虚拟环境与 Kernel 的关系

为什么要在虚拟环境中安装 Jupyter
如果在系统全局 Python 中安装 Jupyter，所有项目共享同一套包，容易出现版本冲突（项目A需要 numpy 1.24，项目B需要 numpy 2.0）。在虚拟环境中安装，每个项目有独立的包环境。但注意：在虚拟环境中安装的 Jupyter 启动时，Kernel 默认是该虚拟环境的 Python，不会自动显示其他环境的 Kernel。
将虚拟环境注册为 Kernel
如果希望在一个 Jupyter 实例中切换不同虚拟环境的 Kernel（如同时对比 Python 3.10 和 3.12），需要在每个虚拟环境中安装 ipykernel 并注册：python -m ipykernel install --user --name=myenv --display-name="Python (myenv)"。注册后重启 Jupyter，New 菜单中会出现该 Kernel 选项。
pip 还是 conda？
两者都能安装 Jupyter，但场景不同：pip + venv 是 Python 标准做法，适合纯 Python 项目；conda 适合需要非 Python 依赖的科学计算（如 CUDA、HDF5、C 扩展库），conda 能管理二进制依赖。数据科学项目推荐 conda/mamba；Web 开发项目推荐 pip + venv。不要混用 pip 和 conda 安装同一个包，容易造成环境损坏。

远程访问 Jupyter

# 在远程服务器上启动，监听所有网卡
$ jupyter notebook --ip=0.0.0.0 --port=8888 --no-browser

# 从本地通过 SSH 隧道安全访问（推荐）
$ ssh -L 8888:localhost:8888 user@remote_server

# 之后在本地浏览器打开：
# http://localhost:8888/?token=...
WARNING 直接用 --ip=0.0.0.0 暴露 Jupyter 到公网非常危险——任何人都可以在你的服务器上执行任意代码。生产环境必须：(1) 设置强密码；(2) 用 SSH 隧道；(3) 或在 Nginx 反向代理后面加 HTTPS + 认证。

常见安装问题排查

问题：jupyter 命令找不到（command not found）
原因是 Jupyter 安装在虚拟环境中但当前 shell 没有激活该环境，或者安装路径不在 PATH 中。解决方法：① 确认虚拟环境已激活（source myenv/bin/activate）；② 用 python -m jupyter notebook 代替直接调用 jupyter notebook；③ conda 环境用 conda activate env_name 激活后再调用。
问题：端口 8888 已被占用
终端会提示 "port 8888 is already in use" 并自动尝试 8889。如果想指定端口：jupyter notebook --port=8890。如果想彻底结束占用端口的进程：lsof -ti:8888 | xargs kill（macOS/Linux）。这通常是前一次 Jupyter 没有正常关闭留下的残留进程。
问题：打开浏览器后显示 Token 不对
每次启动 Jupyter 都会生成新的 Token，从终端输出的 URL 中复制最新的 Token。或者在终端运行 jupyter server list 查看当前活跃的服务器和对应 Token。永久解决：使用 jupyter notebook password 设置固定密码，以后登录输入密码即可，无需每次复制 Token。
问题：安装了包但 Notebook 中 import 失败
最常见原因：在系统 Python 中用 pip 安装了包，但 Notebook 使用的 Kernel 是另一个虚拟环境的 Python。解决方法：确认 Notebook 当前使用的 Kernel 是哪个环境（右上角 Kernel 名称），然后在该环境中安装包。最保险的做法：在 Notebook 中运行 import sys; print(sys.executable) 查看当前 Kernel 的 Python 路径，然后用该路径对应的 pip 安装包：!{sys.executable} -m pip install package_name。

Jupyter 版本说明

版本启动命令特点推荐程度
Notebook 6.x（经典）jupyter notebook成熟稳定，扩展多教学/旧项目
Notebook 7.x（新版）jupyter notebook基于 JupyterLab 技术栈重写新安装默认
JupyterLab 4.xjupyter lab现代 IDE 界面，插件丰富推荐
VS Code Jupyter在 VS Code 中打开 .ipynb集成 IntelliSense，适合大项目开发场景
Google Colab浏览器访问免费 GPU，无需安装实验/教学
新手安装建议

如果你刚开始学习，推荐最简单的安装路径：pip install jupyterlab，然后 jupyter lab 启动。JupyterLab 是 Jupyter 项目的现代版本，界面更友好，功能更完整，且与经典 Notebook 完全兼容（打开 .ipynb 文件方式相同）。不需要同时安装 notebook 和 jupyterlab 两个包——安装 jupyterlab 后，两个命令都可以用。

本章小结

本章核心要点