从零起步掌握 Jupyter Notebook 与 JupyterLab 中 Python 包的安装、配置、排错与管理全流程,覆盖 conda、pip、离线、代理、虚拟环境、依赖解析、扩展集成等核心场景,助您构建稳定、高效、安全的开发环境。
在 Jupyter Notebook 或 JupyterLab 的代码单元格中,可通过 shell 命令前缀 ! 执行 pip 或 conda:
⚠️ 注意:该方式仅对当前内核会话有效,重启后需重新安装;且若内核启动时未指定环境,可能安装到系统全局 Python(非虚拟环境),造成依赖污染。
在终端激活目标虚拟环境后,执行:
安装完成后,需在 Jupyter 中注册该环境为内核:
随后在 Jupyter 界面中切换至 Python (myenv) 内核,即可使用已安装包。
conda 不仅管理 Python 包,还管理底层 C 库、编译器依赖,适合科学计算栈:
推荐使用 conda-forge 频道,其维护更活跃、版本更新及时、兼容性更好:
当服务器无外网权限时,可预先下载轮子文件(.whl)或源码包(.tar.gz),再本地安装:
获取 .whl 文件方式:
安装 GitHub/码云等平台上的源码仓库版本:
适用于需测试新功能、修复紧急 bug 的场景,但稳定性较低,建议仅用于开发环境。
JupyterLab 支持扩展插件,扩展其功能:
安装前请确认扩展兼容当前 JupyterLab 版本(如 lab3.x 不兼容 lab4.x 的扩展)。查看已安装扩展:
常见于未使用虚拟环境、尝试向系统目录写入包时:
解决方案:
--user 安装到用户目录(不推荐生产环境):多个包依赖同一底层包但版本要求冲突,例如:
排查与解决流程:
pip check 检查当前环境依赖健康度:网络不稳定或 PyPI 访问受限导致:
解决方案:
某些包(如 torch、tensorflow)未提供当前平台(如 ARM64、Windows on ARM)的预编译 wheel:
解决方案:
不同项目依赖不同版本库,全局安装易导致冲突。虚拟环境本质是独立的 Python 解释器副本,包含独立 site-packages 目录。
典型问题:
方案 1:venv(轻量,推荐)
方案 2:conda(科学计算推荐)
激活环境后,安装 ipykernel 并注册:
注册后,在 Jupyter 界面右上角内核选择器中即可切换至该环境。
假设需维护两个项目:
创建两个环境:
分别注册为内核:proj-a 和 proj-b,在 Jupyter 中一键切换。
导出环境配置:
复现环境:
标准方式,但存在缺陷:
用 pip-compile 生成 requirements.txt 的“锁定版”:requirements.lock.txt,包含所有传递依赖及精确版本。
生成的 requirements.txt 将包含 numpy、pandas 及其所有依赖(如 python-dateutil、pytz、numpy 等)的精确版本号。
集虚拟环境管理、依赖声明、构建发布于一体的工具:
pyproject.toml 中依赖关系清晰,Poetry 自动解析最优依赖树,支持锁定版本(poetry.lock),确保团队协作一致性。
在 Notebook 中检查当前环境路径与包版本:
确保路径与预期虚拟环境一致,避免误用系统 Python。
在服务器上用 root 运行 pip 会污染系统 Python,导致安全漏洞或系统崩溃(如 yum 依赖系统 Python):
正确做法:始终使用虚拟环境;若必须全局安装,用 pipx 或容器化部署。
PyPI 支持项目发布者上传签名文件(.asc),但国内镜像通常不提供。更实用的是:
需在 requirements.txt 中指定哈希值:
哈希值可从 PyPI 页面获取(点击文件名后查看 Hashes 部分)。
敏感项目不应依赖公共 PyPI,应搭建私有仓库(如 DevPI、Artifactory):
同时配置证书验证,防止中间人攻击。
定期检查已安装包的已知漏洞:
或使用 GitHub Dependabot / Python 安全工作流自动监控。
原因:安装到了错误环境(如全局 vs 虚拟环境);未重启内核。
解决:
确认路径与虚拟环境一致。
两者内核机制相同,安装方式一致。区别在于:
File → New → Terminal 打开终端直接安装! 前缀,或外部终端安装后注册内核若残留 .egg-info 目录,可手动删除:rm -rf /path/to/site-packages/numpy-*.egg-info
注意:旧版可能不兼容当前 Python 版本(如 Python 3.12 不支持 numpy < 1.26)。