jupyter 安装python包|www.xservx.com

jupyter 安装python包|全面实战指南

从零起步掌握 Jupyter Notebook 与 JupyterLab 中 Python 包的安装、配置、排错与管理全流程,覆盖 conda、pip、离线、代理、虚拟环境、依赖解析、扩展集成等核心场景,助您构建稳定、高效、安全的开发环境。

一、基础安装方法|主流方式详解

① 在 Notebook 单元格中安装(临时会话)

在 Jupyter Notebook 或 JupyterLab 的代码单元格中,可通过 shell 命令前缀 ! 执行 pip 或 conda:

# 在 Notebook 中安装 requests 包
!pip install requests

⚠️ 注意:该方式仅对当前内核会话有效,重启后需重新安装;且若内核启动时未指定环境,可能安装到系统全局 Python(非虚拟环境),造成依赖污染。

② 使用 pip 安装(推荐常规方式)

在终端激活目标虚拟环境后,执行:

pip install -U pip
pip install numpy pandas scipy matplotlib scikit-learn

安装完成后,需在 Jupyter 中注册该环境为内核:

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

随后在 Jupyter 界面中切换至 Python (myenv) 内核,即可使用已安装包。

③ 使用 conda 安装(推荐科学计算生态)

conda 不仅管理 Python 包,还管理底层 C 库、编译器依赖,适合科学计算栈:

conda install numpy pandas
conda install -c conda-forge jupyterlab

推荐使用 conda-forge 频道,其维护更活跃、版本更新及时、兼容性更好:

conda config --add channels conda-forge
conda config --set channel_priority strict

④ 从本地 .whl 或 .tar.gz 安装(离线场景)

当服务器无外网权限时,可预先下载轮子文件(.whl)或源码包(.tar.gz),再本地安装:

pip install -no-index --find-links=. scipy-1.11.4-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

获取 .whl 文件方式:

  • 从 PyPI 官网下载(https://pypi.org/project/包名/#files)
  • 从第三方镜像站(如清华、阿里云镜像)下载
  • 在同环境、同架构机器上用 pip download 预下载:
pip download scipy==1.11.4 -d ./pkgs

⑤ 从 Git 仓库直接安装(开发版/最新特性)

安装 GitHub/码云等平台上的源码仓库版本:

pip install git+https://github.com/scipy/scipy.git@v1.12.0rc1

适用于需测试新功能、修复紧急 bug 的场景,但稳定性较低,建议仅用于开发环境。

⑥ JupyterLab 扩展安装(增强交互能力)

JupyterLab 支持扩展插件,扩展其功能:

jupyter labextension install @jupyterlab/toc
jupyter labextension install @aquirdturtle/collapsible_headings
jupyter labextension install jupyterlab-plotly

安装前请确认扩展兼容当前 JupyterLab 版本(如 lab3.x 不兼容 lab4.x 的扩展)。查看已安装扩展:

jupyter labextension list

二、常见安装报错与解决方案|真实场景复现

① PermissionError: [Errno 13] Permission denied

常见于未使用虚拟环境、尝试向系统目录写入包时:

# 错误示例
pip install tensorflow
# → PermissionError: Can not remove existing directory '/usr/local/lib/python3.10/site-packages/tensorflow'

解决方案:

  • 创建虚拟环境后安装:
python -m venv ./venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install tensorflow
  • 或加 --user 安装到用户目录(不推荐生产环境):
pip install --user tensorflow

② Conflict for dependency:依赖冲突

多个包依赖同一底层包但版本要求冲突,例如:

# 安装 pandas 时冲突
ERROR: Cannot install numpy==1.24.0 and numpy==1.26.0 because these package versions have conflicting dependencies.

排查与解决流程:

  1. 用 pip check 检查当前环境依赖健康度:
pip check
  1. 查看冲突包的依赖关系:
pip show numpy
  1. 尝试降级/升级冲突包(谨慎操作):
pip install numpy==1.24.0 --force-replace
  1. 终极方案:新建虚拟环境,逐个安装目标包,避免历史污染。

③ ConnectionError / ReadTimeoutError

网络不稳定或 PyPI 访问受限导致:

ERROR: Could not install packages due to an EnvironmentError: HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out.

解决方案:

  • 使用国内镜像加速:
pip install tensorflow -i https://pypi.tuna.tsinghua.edu.cn/simple
  • 或配置永久镜像源:
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
  • 增加超时时间(秒):
pip install tensorflow --timeout=100

④ Platform not supported / wheel not found

某些包(如 torch、tensorflow)未提供当前平台(如 ARM64、Windows on ARM)的预编译 wheel:

ERROR: No matching distribution found for torch==2.0.0 for platform macosx_11_0_arm64

解决方案:

  • 优先使用 conda 安装,其提供跨平台二进制包:
conda install pytorch torchvision torchaudio -c pytorch
  • 或从官方指定源安装(如 PyTorch 官网命令生成器):
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu118
  • 终极方案:源码编译(耗时长、需 GCC/Clang、CMake、MKL 等依赖):
git clone https://github.com/pytorch/pytorch.git
cd pytorch
python setup.py install

三、环境隔离与内核管理|避免依赖污染

① 虚拟环境必要性

不同项目依赖不同版本库,全局安装易导致冲突。虚拟环境本质是独立的 Python 解释器副本,包含独立 site-packages 目录。

典型问题:

② 创建与激活虚拟环境

方案 1:venv(轻量,推荐)

python -m venv project-env
source project-env/bin/activate # Linux/macOS
.\project-env\Scripts\activate # Windows PowerShell

方案 2:conda(科学计算推荐)

conda create -n myenv python=3.11
conda activate myenv

③ 将虚拟环境注册为 Jupyter 内核

激活环境后,安装 ipykernel 并注册:

pip install ipykernel
python -m ipykernel install --user --name project-env --display-name "Python (project-env)"

注册后,在 Jupyter 界面右上角内核选择器中即可切换至该环境。

④ 多环境共存实操案例

假设需维护两个项目:

创建两个环境:

conda create -n proj-a python=3.9 numpy==1.21 pandas==1.3.5
conda create -n proj-b python=3.11 numpy==1.24 pandas==2.0 scikit-learn==1.2

分别注册为内核:proj-a 和 proj-b,在 Jupyter 中一键切换。

⑤ 环境导出与复现(可移植性)

导出环境配置:

# venv 方式:手动复制 site-packages 不可行;推荐用 requirements.txt
pip freeze > requirements.txt
# conda 方式
conda env export > environment.yml

复现环境:

pip install -r requirements.txt
conda env create -f environment.yml

四、依赖管理与版本控制|进阶技巧

① requirements.txt 管理

标准方式,但存在缺陷:

② pip-tools:生成精确依赖

用 pip-compile 生成 requirements.txt 的“锁定版”:requirements.lock.txt,包含所有传递依赖及精确版本。

pip install pip-tools
# 创建 requirements.in,仅写明主依赖
numpy
pandas
# 编译生成精确依赖
pip-compile requirements.in

生成的 requirements.txt 将包含 numpy、pandas 及其所有依赖(如 python-dateutil、pytz、numpy 等)的精确版本号。

③ Poetry:现代依赖管理工具

集虚拟环境管理、依赖声明、构建发布于一体的工具:

pip install poetry
poetry init # 初始化项目,交互式创建 pyproject.toml
poetry add numpy pandas
poetry add -D pytest # 添加开发依赖
poetry shell # 激活虚拟环境

pyproject.toml 中依赖关系清晰,Poetry 自动解析最优依赖树,支持锁定版本(poetry.lock),确保团队协作一致性。

④ Jupyter 内核环境检查

在 Notebook 中检查当前环境路径与包版本:

import sys, site
print("Python executable: ", sys.executable)
print("Site-packages: ", site.getsitepackages())
import numpy
print("NumPy version: ", numpy.__version__)

确保路径与预期虚拟环境一致,避免误用系统 Python。

五、安全安装与风险防控|生产环境必备

① 避免使用 root 权限安装

在服务器上用 root 运行 pip 会污染系统 Python,导致安全漏洞或系统崩溃(如 yum 依赖系统 Python):

⚠️ 危险操作示例

sudo pip install requests

正确做法:始终使用虚拟环境;若必须全局安装,用 pipx 或容器化部署。

② 验证包签名与哈希(防篡改)

PyPI 支持项目发布者上传签名文件(.asc),但国内镜像通常不提供。更实用的是:

pip install --require-hashes tensorflow

需在 requirements.txt 中指定哈希值:

tensorflow==2.14.0 \
--hash=sha256:abc123... \
--hash=sha256:def456...

哈希值可从 PyPI 页面获取(点击文件名后查看 Hashes 部分)。

③ 使用私有包仓库(企业级)

敏感项目不应依赖公共 PyPI,应搭建私有仓库(如 DevPI、Artifactory):

pip install -i https://pypi.mycompany.com/simple --trusted-host pypi.mycompany.com mypkg

同时配置证书验证,防止中间人攻击。

④ 扫描依赖漏洞(安全审计)

定期检查已安装包的已知漏洞:

pip install safety
safety check -full-report

或使用 GitHub Dependabot / Python 安全工作流自动监控。

六、高频问题速查表|真实用户高频问题

Q1:Jupyter 中安装包后找不到?

原因:安装到了错误环境(如全局 vs 虚拟环境);未重启内核。

解决:

  1. 在 Notebook 中运行:
import sys
print(sys.executable)

确认路径与虚拟环境一致。

  1. 重启 Jupyter 内核(Kernel → Restart)。

Q2:JupyterLab 与 Notebook 安装差异?

两者内核机制相同,安装方式一致。区别在于:

Q3:如何卸载包并清理缓存?

pip uninstall numpy
pip cache purge # 清除 pip 缓存

若残留 .egg-info 目录,可手动删除:rm -rf /path/to/site-packages/numpy-*.egg-info

Q4:如何安装旧版本包?

pip install package==1.2.3

注意:旧版可能不兼容当前 Python 版本(如 Python 3.12 不支持 numpy < 1.26)。

Q5:如何查看某包的依赖树?

pip show -freeze | grep -E "^numpy|^pandas"
pipdeptree # 需安装 pipdeptree