★ FEATURED ARTICLE 1. 先搞清楚为什么 Notebook 老是用错环境我最初接触这个问题是因为在同一个项目里同时跑了两个不同版本的深度学习框架一个依赖 Python 3.8一个依赖 Python 3.10。Jupyter Notebook 默认启动时用的是系统 PATH 里那个 Python结果就是我在终端里明明已经conda activate好了进了 Notebook 一查sys.executable发现根本不是当前环境。这个问题的根源在于 Jupyter 的 Kernel 机制——Notebook 本身不直接执行 Python 代码它把代码交给一个独立的 Kernel 进程去跑而 Kernel 对应的是哪一个 Python 解释器完全取决于 Kernel 是怎么注册的。很多初学者会误以为我激活了哪个环境Notebook 就用哪个环境但实际情况是你在终端里激活环境只影响终端里的命令Notebook 启动时只会去找已经注册过的 Kernel 列表。如果你没有把虚拟环境注册成 KernelNotebook 自然找不到它。这篇内容就是要把这个问题彻底讲透。我会从原理到操作覆盖 venv、conda、pipenv 这几类最常见的虚拟环境工具再补充一些多环境管理时的避坑经验。无论你是刚开始用 Jupyter 的新手还是已经被环境问题折磨过几次的老手都可以从中找到对应的解法。2. 核心思路Notebook 的 Kernel 与虚拟环境的对应关系2.1 Kernel 到底是什么简单说Jupyter Notebook 的前端页面只是编辑器你在单元格里写的代码会通过 ZeroMQ 协议发送给后端的 Kernel 进程去执行执行结果再传回前端显示。所以 Notebook 用的到底是哪个 Python 版本、哪个包完全取决于 Kernel 进程是哪个 Python 启动的。这就解释了为什么有时候你在 Notebook 里pip install装了一个包重启 Kernel 之后依然ImportError——因为你 pip 装的这个包是装到了某个环境里但你的 Kernel 是另一个环境启动的。2.2 注册 Kernel 的原理Kernel 的注册信息存放在一个名为kernel.json的文件里里面指定了启动 Kernel 时用的可执行文件路径、启动参数等信息。ipykernel这个包提供了一个命令python -m ipykernel install它会自动把当前正在运行的这个 Python 环境注册到 Jupyter 的 Kernel 列表中。注册的默认路径在用户目录下的.local/share/jupyter/kernels/Linux/Mac或%APPDATA%\jupyter\kernels\Windows里。你可以在终端里执行jupyter kernelspec list查看当前已经注册了哪些 Kernel以及它们各自对应的路径。2.3 核心操作三步法不管你是用哪种虚拟环境工具核心操作就三步激活目标虚拟环境确保终端里which pythonWindows 是where python指向的是这个环境的解释器。在激活的环境里安装ipykernel包。执行python -m ipykernel install --user --name 环境名完成注册。这三步做完之后重启 Jupyter Notebook在 Kernel 切换菜单里就能看到你注册的环境名了。3. 实操以 conda 虚拟环境为例的完整过程3.1 创建并激活环境假设我要创建一个名为ml_dev的 conda 环境指定 Python 3.9 版本conda create -n ml_dev python3.9 -y conda activate ml_dev激活之后先确认一下当前解释器路径which python如果输出路径里有ml_dev这个字样说明环境切换成功。这一步很关键因为后面所有操作都依赖于当前终端用的是目标环境这个前提。3.2 安装 ipykernel 并注册在激活的环境里执行pip install ipykernel python -m ipykernel install --user --name ml_dev --display-name Python (ml_dev)这里解释一下参数含义--user表示只对当前用户注册 Kernel不需要系统管理员权限。--name是 Kernel 的内部标识名也就是jupyter kernelspec list里显示的名字。--display-name是 Notebook 界面中显示的名字可以随意取方便识别。注册完成后执行jupyter kernelspec list确认jupyter kernelspec list正常情况下会看到多了一条ml_dev的记录。3.3 在 Notebook 中切换 Kernel重启 Jupyter Notebook如果之前开着的话新建一个 Notebook在界面的 Kernel 菜单中选择 Change Kernel然后选择Python (ml_dev)。或者新建 Notebook 时直接选择这个 Kernel。验证是否生效的方法在单元格里执行import sys print(sys.executable)如果输出的路径指向ml_dev环境下的 python说明切换成功。再顺手验证一下包的版本import numpy print(numpy.__version__)这样基本可以确定当前 Kernel 用的确实是目标环境。4. 实操venv 虚拟环境的注册方法与差异点4.1 venv 与 conda 的差异venv 是 Python 自带的虚拟环境工具和 conda 最大的区别在于venv 只隔离 Python 包不隔离 Python 解释器版本。也就是说venv 创建出来的环境用的还是创建时指定的那个 Python 版本不会像 conda 那样能直接指定安装 Python 3.9 或 3.10。4.2 创建并注册 venv 环境python -m venv fastapi_env source fastapi_env/bin/activate # Windows 下是 fastapi_env\Scripts\activate激活后同样安装 ipykernel 并注册pip install ipykernel python -m ipykernel install --user --name fastapi_env --display-name Python (fastapi_env)这里的操作和 conda 几乎一模一样唯一区别在于环境创建和激活的方式。4.3 遇到找不到 python的情况怎么办有时候在 Windows 上激活 venv 后执行python会跳到微软商店的别名这是因为系统 PATH 里混入了应用执行别名。解决办法是在激活 venv 后确认where python的输出中是否包含当前 venv 路径下的Scripts\python.exe。如果优先级不对可以直接用全路径调用fastapi_env\Scripts\python.exe -m ipykernel install --user --name fastapi_env这也是为什么我建议在注册 Kernel 之前先验证一下解释器路径避免用错了环境注册。5. 实操让项目自动选择虚拟环境可选进阶技巧5.1 为什么需要这个功能当你在多个项目之间切换时每次都手动去 Kernel 菜单里切换环境既麻烦又容易出错。特别是项目文件较多、中间隔了几天再回来时很容易忘记当时用的是哪个环境。5.2 方案一ipykernel 配合 jupyter kernelspec 的默认配置Jupyter Notebook 在选择 Kernel 时会记录当前 Notebook 文件对应的 Kernel 名称。也就是说你只要在首次使用时手动选对一次 Kernel保存后这个 Notebook 文件就固定绑定到那个 Kernel 了。下次打开同一个文件Jupyter 会自动使用绑定好的 Kernel。这个机制本身已经很实用适合大多数场景。5.3 方案二使用环境变量自动区分如果你在一个 Notebook 里需要根据环境变量切换不同的依赖库版本可以在代码开头做判断import os import sys env_name os.environ.get(CONDA_DEFAULT_ENV, ) if env_name ml_dev: import tensorflow as tf else: import torch这属于业务逻辑层面的处理本质上是让同一份代码兼容不同环境适合在实验对比阶段使用。5.4 方案三session 级别的 Kernel 管理如果你用的是 Jupyter Lab可以安装jupyterlab-lsp、jupyterlab-git这类插件但它们并不会影响 Kernel 选择。真正影响 Kernel 选择的是内核管理器。Jupyter Lab 3.x 版本会在侧边栏显示当前 Kernel 信息方便目视确认但自动选择依然要靠手动配置。6. 常见问题与排查技巧实录6.1 注册了 Kernel 但 Notebook 里看不到这种情况最常见的原因是 Jupyter 启动时使用的用户目录和注册 Kernel 时的用户目录不一致。比如你在终端里用sudo jupyter notebook启动而注册 Kernel 时用的是普通用户那 Kernel 列表就对应不上。排查方法在终端里执行jupyter kernelspec list看看你注册的 Kernel 是否在列表里。如果在但 Notebook 里看不到大概率是 Jupyter 进程的用户权限问题。6.2 Kernel 启动报错显示Failed to start kernel这类问题通常是 Kernel 启动时依赖的包缺失或 Python 版本不匹配。排查思路先尝试在终端里手动执行 kernel.json 里指定的命令看报错信息是什么。典型的报错场景是Kernel 注册时用的 Python 路径已经失效比如 conda 环境被删除这时候重新注册一次就好。6.3 在 Notebook 里 import 模块失败但终端里 import 成功这是最让人抓狂的一种情况。原因基本可以锁定为Notebook 的 Kernel 不是当前终端激活的那个环境。我之前就犯过这个错——在终端里conda activate之后顺手在 Notebook 里装了个包结果发现装到了 base 环境而 Kernel 是另一个环境。解决方案永远是先确认 Kernel 对应的环境再在那个环境里安装包。安装包时建议用python -m pip install而不是pip install这样可以避免 pip 指向系统环境的问题。6.4 多个虚拟环境之间包版本冲突怎么办如果你需要在多个环境之间频繁切换建议为每个环境创建独立的 Kernel 名称并且命名时带上版本信息比如ml_dev_py39、api_dev_py310。这样在 Notebook 里切换时一目了然也能减少误用环境的概率。另外补一个实用小技巧在 Notebook 里随时执行以下代码快速查看当前环境状态import sys print(sys.executable) print(sys.version) import site print(site.getsitepackages())这样你能同时在代码里确认解释器路径和安装路径快速判断环境是否用对。6.5 Jupyter 安装在系统环境但虚拟环境里没装 jupyter这种情况其实不影响使用。Jupyter Notebook 只是一个前端编辑器它通过 Kernel 协议和后端通信所以哪怕你的 Jupyter 装在系统环境、Kernel 装在虚拟环境只要 Kernel 注册成功Notebook 就能正常用虚拟环境的包。但如果你在虚拟环境里直接执行jupyter notebook会提示找不到命令。这时候有两种方案一是用系统环境的 Jupyter二是给虚拟环境也装一份 Jupyterpip install jupyter jupyter notebook我个人倾向于第一种因为系统环境的 Jupyter 版本升级不会污染虚拟环境而且 Jupyter 本身并不影响代码执行结果。7. 工具选型解析conda vs venv vs pipenv面对虚拟环境工具选型我整理了这些年实际使用的心得。这里列个对比表方便你在项目开始前就选对工具对比维度condavenvpipenvPython 版本隔离支持可安装任意版本不支持依赖系统 Python支持可指定版本包管理器conda / pippippip自动管理依赖依赖锁定支持导出 yaml通过 requirements.txt通过 Pipfile.lock学习成本较高低中等适合场景数据科学/深度学习轻量级 Python 项目Web 开发/依赖管理从 Jupyter 集成角度看conda 和 venv 都是直接使用 ipykernel 注册差别不大。pipenv 稍微特殊一点因为它会自动创建一个虚拟环境并且自动激活注册 Kernel 前需要先手动pipenv shell进入环境再执行 ipykernel 注册。我在实际项目中更推荐 conda原因有三点它能直接安装指定版本的 Python避免因为系统 Python 版本太低而无法使用一些新特性。conda 自带的包管理在安装数据科学类库numpy、pandas、scipy 等时速度更快且极少遇到编译报错。团队协作时导出 environment.yaml 文件比 requirements.txt 更直观还包含了 channels 信息。但这不代表 venv 没有价值。如果你的项目是纯 Python 项目、不涉及数据分析venv 的轻量反而更合适因为它不需要额外安装 conda 这类工具。8. 多环境管理的高级技巧与个人经验总结8.1 为每个项目创建独立 Kernel 的好处当你在同一个 Jupyter 实例里打开多个项目时独立 Kernel 能避免一个 Notebook 的错误影响到另一个 Notebook。比如你在项目 A 里执行了pip install xxx如果 Kernel 混用项目 B 可能会因此被污染。为每个项目分配独立 Kernel 后这种交叉污染几乎为零。8.2 命名规范建议我个人的习惯是Kernel 名称由项目代号 Python 版本组成。例如recsys_py38推荐系统项目Python 3.8nlp_py39NLP 项目Python 3.9这样做的好处是哪怕未来 You 升级了项目依赖也能通过名称快速定位到需要的环境。8.3 配合 Jupyter Lab 的使用经验如果你已经转向 Jupyter Lab那么点击左侧的内核面板就能看到当前会话对应的 Kernel切换更方便。同时Jupyter Lab 的多标签特性允许你在同一个页面里同时打开不同 Kernel 的 Notebook非常利于对比实验。我个人在实验阶段的固定流程是创建独立环境装好基础依赖。注册 Kernel命名带上版本号。启动 Jupyter Lab每个实验开一个 Notebook对应不同 Kernel。实验结束导出 requirements.txt 或 environment.yaml备份后删除环境。这个过程走下来几乎没有再被环境问题卡住过。8.4 最后再分享一个排查小技巧当 Kernel 启动异常或者找不到模块时不要急着重新安装整个环境。先在终端里直接执行 kernel.json 里的命令比如/home/user/miniconda3/envs/ml_dev/bin/python -m ipykernel_launcher -f /tmp/kernel.json这样可以绕过 Jupyter 的前端直接看到 Kernel 进程的完整日志。很多问题比如缺少依赖包、Python 动态库加载失败都会被直接打印出来排查效率极高。以上内容基于我日常使用 Jupyter Notebook 管理虚拟环境的全部经验和教训希望能帮你在环境这个隐形坑上少走弯路。
阅读完成 · 觉得有帮助？
