Jupyter Notebook 安装与配置实操教程

适用于 Windows / Linux 系统 | Python 3.x | pyenv 环境管理

第一步：配置 Python 版本并升级 pip

1.1 使用 pyenv 管理 Python 版本

pyenv 是一个 Python 版本管理工具，可以方便地在多个版本之间切换。首先查看已安装的版本：

>> pyenv versions
  3.10.11
* 3.10.9  (set by C:\Users\alan\.pyenv\pyenv-win\version)
  3.11.9
  3.12.9
  3.8.9

切换到目标版本（此处以 3.12 为例）并验证：

>> pyenv global 3.12
>> python --version
Python 3.12.9

💡 提示：如果尚未安装 pyenv，Windows 用户可访问 pyenv-win 按文档安装；Linux/macOS 用户可使用官方安装脚本。

1.2 升级 pip

建议在安装任何包之前，先将 pip 升级到最新版本：

>> pip install --upgrade pip

如果出现权限提示，改用以下完整路径命令（以 Windows Python 3.12.9 为例）：

>> C:\Users\alan\.pyenv\pyenv-win\versions\3.12.9\python.exe -m pip install --upgrade pip
Successfully installed pip-26.0.1

升级完成后验证版本：

>> pip --version
pip 26.0.1 from ...\Lib\site-packages\pip (python 3.12)

⚠️ 注意：Windows 系统中直接运行 pip install --upgrade pip 有时会因权限问题失败，此时需改用 python.exe -m pip install 的方式。

第二步：安装并配置 Jupyter Notebook

2.1 安装 Notebook

>> pip install notebook

安装完成后，可运行以下命令确认版本：

>> jupyter notebook --version

2.2 生成并修改配置文件

生成默认配置文件：

>> jupyter notebook --generate-config
Writing default config to: 'C:\\Users\\alan\\.jupyter\\jupyter_notebook_config.py'

用文本编辑器（如 VS Code、Notepad++）打开该配置文件，找到并修改以下配置项，将默认工作目录设置为你想要存放文件的路径：

# 修改前（默认注释状态）：
# c.ServerApp.root_dir = ''

# 修改后（取消注释并填写路径）：
c.ServerApp.root_dir = 'D:\\JupyterNotebook'

💡 提示：Windows 路径中的反斜杠需要转义，写成 \\，或使用正斜杠 D:/JupyterNotebook 均可。确保该目录已提前创建，否则 Notebook 启动时可能报错。

2.3 安装中文语言包（可选）

>> pip install jupyterlab-language-pack-zh-CN

安装完成后，启动 Notebook，进入 Settings（设置）→ Language（语言），选择「中文（简体）」并点击「Change and Reload」使语言设置生效。

第三步：启动 Jupyter Notebook

3.1 普通用户启动

在终端中执行：

>> jupyter notebook

启动成功后，终端会输出访问链接：

[I] Serving notebooks from local directory: D:\JupyterNotebook
[I] Jupyter Server 2.x.x is running at:
[I]   http://localhost:8888/tree?token=xxxxxxxxxxxxxxxx
[I]   http://127.0.0.1:8888/tree?token=xxxxxxxxxxxxxxxx

复制任意一个链接（含 ?token=... 参数）粘贴到浏览器中即可访问。

3.2 Root 用户启动（Linux）

在 Linux 系统中以 root 身份运行时，直接执行会收到警告，需添加 --allow-root 参数：

# 普通启动会报错：Running as root is not recommended.
>> jupyter notebook

# 正确方式：
>> jupyter notebook --allow-root

⚠️ 注意：在生产或多用户服务器环境中，不建议长期以 root 身份运行 Jupyter Notebook，存在安全风险，建议创建普通用户来运行服务。

3.3 关闭 Notebook 服务

在终端中按 Ctrl+C 停止服务器，系统会要求二次确认，再次按 Ctrl+C 或输入 y 即可关闭。

常见问题与排查

Q1：浏览器没有自动打开？

复制终端输出的完整链接（包含 ?token=... 部分）手动粘贴到浏览器地址栏打开。

Q2：端口 8888 被占用？

>> jupyter notebook --port=8889

Q3：pip 安装速度慢？

可临时使用国内镜像源加速，例如清华源：

>> pip install notebook -i https://pypi.tuna.tsinghua.edu.cn/simple

Q4：如何在虚拟环境中使用独立内核？

激活虚拟环境后，将其注册为 Jupyter 的内核：

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

至此，Jupyter Notebook 已完成安装、配置与启动。祝使用愉快！