最近好几个朋友跑来问我同一个问题明明在 conda 里创建了新环境也装好了想要的包打开 Jupyter Lab 一看内核列表里永远只有那个默认的 Python 3选的还是默认内核跑起来后所有自定义安装的库全部 ModuleNotFoundError。我刚开始用 conda 管理 Python 环境时也被这个坎卡了好几天。查了一堆资料试过conda install jupyter、pip install jupyter折腾到怀疑人生。后来才搞清楚Jupyter 根本不会自动去探测你电脑里有几个 conda 环境它只认一份内核注册表。只要你没把 conda 环境“登记”进去它对你再多的 Python 环境也是视而不见的。这篇文章就把这件事彻底讲透你会明白内核注册的底层逻辑、拿到一组可以照抄的命令、还会收获一份我整理好的问题排查手册。适合所有用 conda 管理环境、又被 Jupyter 默认内核坑过的 Python 使用者。1. Jupyter 为什么看不到新建的 conda 环境内核注册机制的底层逻辑1.1 内核不是环境先搞清楚 Jupyter 眼里“内核”到底是什么很多人把“内核”和“Python 环境”划等号这其实是误解的根源。Jupyter 里说的内核kernel本质上是一份“配置说明书”告诉 Jupyter 这个内核显示成什么名字、用哪里的 Python 解释器去跑代码。打个比方。你买了一台新电脑系统不会自动知道你的打印机怎么用必须安装驱动程序系统才能识别并调用它。Jupyter 的整体架构也是这套逻辑内核就是一个“驱动程序”而 conda 环境里那个真实的 Python 解释器是被驱动的硬件。正常情况下Jupyter 安装包会附带一个默认内核这个内核指向的就是你安装 Jupyter 时所在的那个 Python 解释器。如果你是在 base 环境里装 Jupyter那默认内核当然就指向 base 的 Python。这时候你在终端里conda activate myenv激活新环境这只影响终端这个进程和 Jupyter 没有任何关系。Jupyter 依然用自己注册表里的默认内核去干活自然看不到 myenv 里的任何包。1.2 kernelspec 注册表Jupyter 从哪里找内核Jupyter 在启动时会去几个固定目录里扫描“内核规格”kernelspec。每个内核规格都是一个文件夹里面有一个kernel.json文件记录了启动内核时要执行的命令和参数。不同操作系统上的目录位置如下操作系统用户级目录--user 安装系统级目录Windows%APPDATA%\jupyter\kernels\C:\ProgramData\jupyter\kernels\Linux/macOS~/.local/share/jupyter/kernels//usr/local/share/jupyter/kernels/Jupyter 启动时会依次扫描这些目录把所有找到的 kernelspec 都显示在“新建 Notebook”的下拉列表里。也就是说你要想让新建的 conda 环境出现在列表里实质工作只有一个帮这个环境生成一份 kernelspec让 Jupyter 能找到它。这份 kernel.json 的核心内容大致长这样{ argv: [ /home/你的用户名/anaconda3/envs/myenv/bin/python, -m, ipykernel_launcher, -f, {connection_file} ], display_name: Python (myenv), language: python, metadata: { interpreter: { hash: , name: python, path: /home/你的用户名/anaconda3/envs/myenv/bin/python } } }这里面的argv第一条就是关键它指向 myenv 环境里的 Python 解释器。只要这条路径正确Jupyter 启动这个内核时就会用 myenv 的 Python 去执行代码你在这个环境里 pip/conda 安装的包自然全部可见。1.3 为什么“换了环境”却还是 base 的包经常有人这样操作在 base 环境里pip install ipykernel然后跑python -m ipykernel install --namemyenv结果发现新内核虽然出现了但 import 的仍然是 base 的包。原因就是你用哪个 Python 解释器执行注册命令生成的内核就会指向那个解释器。你在 base 里安装 ipykernel用 base 的 python 去执行注册就算名字起得再花哨生成的 kernel.json 第一条 argv 指向的还是 base 的 Python。这就好比给打印机装了错误的驱动设备名字写对了但驱动硬件的还是老版本的跑起来自然不对。原理搞明白了接下来就可以真正解决问题了。2. 三步完成环境到内核的注册从装 ipykernel 到显示在内核列表2.1 前提确认先让 conda 环境本身没问题在动 Jupyter 之前先确认目标环境状态正常。打开终端执行conda env list正常情况下会看到类似这样的输出# conda environments: # base /home/用户名/anaconda3 myenv * /home/用户名/anaconda3/envs/myenv这里的 * 表示当前激活的环境。如果你的环境不存在先创建并安装基础包conda create -n myenv python3.11然后激活它conda activate myenv如果你在 Windows 的 PowerShell 里遇到 “无法将 conda 项识别为 cmdlet、函数、脚本文件或可运行程序的名称” 这种报错先不要慌跳过激活直接用conda run就行。我后面专门讲这个坑。2.2 核心命令三行代码把环境注册成内核前提确认好了就进入正题。在目标环境激活状态下依次执行三条命令pip install ipykernel这一步是在当前环境里安装内核启动器。ipykernel 提供ipykernel_launcher这个模块kernel.json 里的 argv 才会指向它。没有这个东西内核根本起不来。python -m ipykernel install --user --name myenv --display-name Python (myenv)这步就是“注册”动作。解释一下参数--user把内核规格写到用户级目录不需要管理员权限。如果你不加--user默认会尝试写入系统级目录在 Linux/macOS 上经常会因为权限不足报错。--name机器识别名也是文件夹名字。只能用小写字母、数字和下划线不能用空格不能有中文。以后清理内核时要用这个名字。--display-name界面上显示的名字。你可以随便起中文也行这里只是为了在 Jupyter 界面上好认。执行完看到Installed kernelspec myenv in /home/用户名/.local/share/jupyter/kernels/myenv类似输出就说明注册成功了。2.3 验证是否生效让内核真正跑起来注册不等于大功告成一定要验证。在 Jupyter Lab 界面里刷新浏览器页面不是关标签页是整体刷新。如果 Jupyter Lab 已经开着按 F5 或 CtrlShiftR 强制刷新。点左上角“文件”里的“新建笔记本”这时下拉列表里应该出现Python (myenv)。选这个新内核然后在单元格里执行下面两行代码import sys print(sys.executable)如果输出的是 myenv 环境里的 Python 路径比如/home/用户名/anaconda3/envs/myenv/bin/python或者 Windows 上的D:\Anaconda3\envs\myenv\python.exe那就说明内核已经正确指向新环境了。此时再执行import os print(os.getcwd())只是为了确认工作目录是否符合预期。重点就看sys.executable。很多教程到这里就结束了但实际使用中你会遇到各种幺蛾子下面这部分是我踩坑踩出来的。3. 内核定位问题排查实录从报错到修复的完整链路3.1 conda 命令无法识别Shell 初始化问题我见过最多的情况就是用户在 Windows PowerShell 里输入conda activate直接报错无法将“conda”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。原因是 conda 安装后它需要往你的 shell 配置文件里写入初始化脚本。PowerShell 和 CMD 的初始化方式不一样很多时候安装完 conda 后没有正确执行过初始化。处理方法很简单先打开 Anaconda Prompt开始菜单里一般有在里面执行conda init powershell或者如果你是用的 Windows Terminal直接在 PowerShell 配置里加上 conda 初始化脚本。操作完需要重开一个终端让配置生效。如果你不想纠缠 shell 激活的问题直接用conda run命令绕过conda run -n myenv pip install ipykernel conda run -n myenv python -m ipykernel install --user --name myenv --display-name Python (myenv)conda run的作用是在指定环境内执行命令完全不需要你手动激活。这条命令对我这种经常在自动化脚本里切换环境的人特别好用省掉了激活失效、PATH 错乱一堆麻烦事。3.2 内核能启动但 import 不到目标环境的包这个坑最容易让人怀疑人生。内核列表里明明有Python (myenv)选择它之后 notebook 也能开看起来一切正常但一import sklearn就报 ModuleNotFoundError。先说结论大概率是你的内核注册有问题kernel.json 里指向的还是 base 或者别的环境的 Python。你可以先做个快速诊断在 notebook 里执行import sys print(sys.executable)再在终端里执行conda run -n myenv python -c import sys; print(sys.executable)如果两个输出不一致说明内核指向错了。修复方法也直接conda run -n myenv pip uninstall ipykernel -y conda run -n myenv pip install ipykernel --upgrade conda run -n myenv python -m ipykernel install --user --name myenv --display-name Python (myenv) --force这里加了--force参数意思是即使同名内核已经存在也强制覆盖。我之前说过用哪个 python 执行注册命令生成的内核就指向哪个 python。你只要把命令前头带上conda run -n myenv就能保证用对解释器。那为什么会出现指向错误呢最常见的原因是有人在 base 环境里创建了 myenv 的内核文件却以为自己在 myenv 里注册。另外如果你之前把某个第三方 IDE 自带的内核规格复制过目录也可能造成这种错乱。排查思路就一条确认 kernel.json 里的路径或者更简单直接重装重注册一条龙解决。3.3 同名内核残留和清理搞多了以后你的内核列表很容易堆积一堆名字类似的垃圾内核。比如myenv、myenv1、myenv-copy这些到底对应哪个环境时间一久根本分不清。先看当前有哪些内核jupyter kernelspec list输出结果会列出所有已注册的内核名和对应路径。再确认某个内核到底指向哪个 Python直接看它的 kernel.jsoncat ~/.local/share/jupyter/kernels/myenv/kernel.jsonWindows 用type %APPDATA%\jupyter\kernels\myenv\kernel.json确认是垃圾内核后直接移除jupyter kernelspec remove myenv-copy这个命令要求输入y确认然后内核删除。这么做不比你手动删文件夹安全吗安全得多。Jupyter 本身有一套缓存直接删文件不刷新的话界面上可能还会残留旧条目。用官方命令删会同步清掉缓存痕迹。3.4 内核无限重启“假死”的处理还有一种更气人的情况内核选了单元格一执行就显示“内核正忙可能需要重启”然后死循环或者内核状态一直显示“正在连接”永远等不到结果。几个常见触发原因我都遇过ipykernel 版本太老。conda 环境是你几个月前建的里面 ipykernel 还是老版本和当前 Jupyter Lab 版本的通信协议不兼容。解决办法conda run -n myenv pip install ipykernel --upgrade conda run -n myenv python -m ipykernel install --user --name myenv --force --display-name Python (myenv)kernel.json 被改坏了。有时候你会手动编辑 kernel.json 去调整路径结果 JSON 格式写错Jupyter 读不进去。检查方法python -m json.tool ~/.local/share/jupyter/kernels/myenv/kernel.json如果输出 JSON 解析错误说明文件格式有问题。重写一遍或者干脆走卸载重注册流程。环境里的 Python 本身损坏。这种情况比较少见但如果你曾经在环境里手动删过文件或者中断过包安装Python 解释器可能已经不完整。最快方式就是重建环境conda create -n myenv --clone myenv_bak或者干脆删掉重建。重建之后重新注册内核问题一般就消失了。buffered 和 timeout 参数问题。终端里看到类似[IPKernelApp] WARNING | debugpy: ...或者内核启动日志卡住不动可以尝试给 kernel.json 加一行环境变量env: { PYDEVD_DISABLE_FILE_VALIDATION: 1 }这个主要针对调试器和代码验证导致的启动阻塞。说实话这种情况不是每个用户都会遇到但我在 Windows 上确实被它卡过一整晚。加上这个之后内核启动明显快了。如果你是在跑深度学习的工程还要注意内存问题内核占用的内存超过上限一样会假死那种情况不是配置问题是资源问题。3.5 注册成功但 Jupyter 不显示还有一种让人哭笑不得的场景jupyter kernelspec list里明明能看到 myenv重启了 Jupyter Lab新笔记本下拉列表里还是找不到。这个很多时候是缓存。你在 Windows 上Jupyter Lab 走的是本地 URL http://localhost:8888 浏览器对 /api/kernelspecs 这个接口做了缓存导致刷新不及时。处理顺序我建议这样先浏览器强制刷新CtrlShiftR 或 CtrlF5如果不行重新启动 Jupyter Lab 服务进程不是刷新页面是把终端里跑 jupyter lab 的那个进程 CtrlC 停掉再重新启动还不行用无痕窗口打开 Jupyter Lab 看看最后才考虑是不是注册目录扫不到——检查你安装内核时用的是不是和启动 Jupyter 的同一个用户权限。sudo pip install注册的内核写在 root 用户目录下普通用户启动的 Jupyter 是搜不到的这类问题有个通吃解法在 base 环境里装jupyter和nb_conda_kernels让 Jupyter 自动发现所有 conda 环境就绕过了手工注册的各种意外。4. 比逐个手敲命令更省心的做法插件自动发现与批量注册脚本4.1 nb_conda_kernels让 Jupyter 自动扫描 conda 环境如果你经常创建新的 conda 环境每次手动注册内核确实繁琐而且容易忘。我推荐在 base 环境安装nb_conda_kernels它能让 Jupyter 自动枚举你机器上所有 conda 环境并在界面上显示为独立内核。conda activate base conda install nb_conda_kernels -c conda-forge安装完成后重启 Jupyter Lab你会发现新笔记本的内核列表里多了一堆带环境名后缀的内核每个对应一个 conda 环境。选择一个环境执行代码Jupyter 会自动调用该环境的 Python不需要你手动注册 kernel。这个方案优点很突出以后你新建 conda 环境只要环境里装了 ipykernelJupyter 刷新后就能自动识别不用再敲注册命令。缺点也有就是其识别逻辑依赖环境的envs目录结构如果你用虚拟环境venv或手动改了路径它可能扫不到这时候还是得回到手工注册的路子。4.2 批量注册给所有 conda 环境一次性生成内核如果你不想装插件就想用最原生的手工方式但又想一口气把所有环境全部注册可以写一个小循环。Linux/macOS 下在终端里这样写for env in $(conda env list | awk {print $1} | grep -v ^#); do if [ $env ! base ]; then source $(conda info --base)/etc/profile.d/conda.sh conda activate $env pip install -q ipykernel python -m ipykernel install --user --name $env --display-name Python ($env) --force fi doneWindows PowerShell 下的写法略有不同需要先拿到环境列表然后逐个调用 conda runconda env list | ForEach-Object { if ($_ -match ^\S\s(\S)$ -and $Matches[1] -ne base) { $envName ($_ -split \s)[0] conda run -n $envName python -m ipykernel install --user --name $envName --display-name Python ($envName) --force } }执行完用jupyter kernelspec list确认数量是否对。这个方案在环境数量超过 5 个时特别香一次操作终身受用。新机器迁移过来时同理跑一遍全部搞定。4.3 跨机器迁移别把 kernel.json 拷过去最后提醒一个很容易犯的错误有人觉得把~/.local/share/jupyter/kernels/整个目录打包拷贝到新机器就完事了。确实如果两台机器上 conda 目录结构完全一致这么做能跑但问题是你的 conda 安装路径稍微变一下kernel.json 里的绝对路径就失效了内核会直接启动失败。原因是 kernel.json 里存放的都是死路径。比如你老机器上环境在/home/alice/anaconda3/envs/ml新机器用户名是bob环境装在了/home/bob/miniconda3/envs/ml那么这份配置文件就是废的。正确的迁移姿势是新机器上把 conda 环境建好环境列表conda env list确认无误直接重新批量注册一次即可有心人几秒钟就跑完了没必要拷贝 config 文件。还有个小技巧值得分享创建环境的时候就顺手把 ipykernel 装进去这样后面不管哪个环境都能直接注册不用临时补装conda create -n myenv python3.11 ipykernel这个习惯能让你后面所有环境开箱即用非常实用。4.4 与 VSCode 的联动机制顺带说一句很多人在用 VSCode 写 Jupyter notebook也会遇到同样的问题VSCode 里选了 conda 环境但 Jupyter 内核还是默认的。其实 VSCode 的 Jupyter 插件在寻找内核时就是依靠同一套 kernelspec 机制。也就是说你在终端里把这套注册流程跑通了VSCode 里同样受益。在 VSCode 的右上角选内核时能看到这里注册出来的Python (myenv)。如果你在终端里注册好却找不到先检查 VSCode 里有没有选择对应的 Jupyter Server 和 Python 解释器VSCode 的设置项有时候会拦截搜索路径但本质上底层还是这套东西。写在最后回顾一下核心逻辑Jupyter 不认识 conda 环境只认 kernelspec 注册表。想让某个 conda 环境成为 Jupyter 的运行内核本质工作就是用该环境的 Python 生成一份内核配置。三条命令解决conda run -n myenv pip install ipykernel conda run -n myenv python -m ipykernel install --user --name myenv --display-name Python (myenv) jupyter kernelspec list # 验证排查时永远先跑sys.executable确认当前 notebook 到底用的哪个解释器这能帮你少走 80% 的弯路。我现在的习惯是每建一个 conda 环境顺手就装好 ipykernel 并注册再把这个动作写进项目初始化脚本里换机器也只要几分钟。希望这篇文章能帮你彻底告别“默认内核运行错误环境”的日子。