刚接触jupyter notebook的人十有八九都遇到过这种情况在New菜单里找不到自己新建的conda环境。我见过太多朋友为了这个问题把Anaconda卸载重装两三遍最后发现根本不是安装的问题而是环境和内核这两个概念从一开始就没分清。这篇就把jupyter notebook添加环境、添加内核这件事一次讲透包括内核的运行机制、三种添加方式、日常管理命令、高频故障排查以及VSCode和远程服务器场景下的配置。全程都是实际操作中验证过的经验按步骤抄就能用。1. 环境和内核有什么区别搞懂这两个概念就不用再瞎折腾1.1 环境是你的工具箱内核是送货单先说结论conda环境environment和jupyter notebook内核kernel是两个完全不同的东西但很多人把它俩当成一回事。conda环境本质上是一个独立的Python运行时目录里面放着自己的Python解释器、pip和site-packages目录。你在环境里装的所有包都堆在这个环境的site-packages里跟其他环境互不干扰。你可以把它想象成一间独立的工具箱箱子里装什么工具完全由你自己决定。建新环境、激活环境、装包都是在收拾这个工具箱。而jupyter notebook里的内核根本不是Python环境本身而是一份**如何启动某个Python进程的说明**。Jupyter Notebook是在浏览器里操作的它本身并不会直接运行Python代码。它做的事是读一份内核配置文件按照配置里的路径去启动对应的Python解释器然后通过一个消息协议跟这个解释器进程通信把代码送过去执行、把执行结果拿回来显示。所以两者的关系可以这样理解环境是装满工具的箱子内核是箱子上的地址标签。jupyter notebook拿到这个标签才知道要去哪里启动解释器。你新建的conda环境不会自动出现在jupyter notebook里因为jupyter notebook只认识内核它不会主动去扫描你的conda环境列表。这就是为什么你明明建了新环境打开jupyter notebook却什么都看不到。很多教程一上来直接教敲命令大家照抄一遍发现没生效原因就是没理解这个逻辑。搞清楚之后你会发现不管是手动注册还是用工具自动发现所有添加内核的方法本质上做的都是同一件事给jupyter notebook写一份指向某个环境的启动说明。1.2 内核配置文件kernel.json里到底写了什么要验证上面的理解最直接的方法是看内核配置文件。当你执行完python -m ipykernel install之后系统里会多出一个内核目录里面有一个kernel.json。在Linux上用户级的内核路径一般是~/.local/share/jupyter/kernels/内核名/kernel.jsonWindows上是C:\Users\你的用户名\AppData\Roaming\jupyter\kernels\内核名\kernel.json。如果你不确定自己的内核装到哪去了执行jupyter --paths看输出的 data 字段列表凡是.../jupyter/kernels结尾的目录就是jupyter找内核的位置。这个json文件长这样{ argv: [ /home/user/miniconda3/envs/myenv/bin/python, -m, ipykernel_launcher, -f, {connection_file} ], display_name: Python (myenv), language: python }关键字段就三个argv启动内核进程时要执行的命令。第一个参数写死的是某个环境的Python解释器绝对路径后面跟-m ipykernel_launcher表示启动ipykernel的启动器{connection_file}是占位符运行时jupyter会把实际连接文件路径填进去。display_name显示在jupyter notebook界面上的名字就是你New菜单里看到的那串。language内核支持的编程语言Python内核这里是python。排查几乎所有内核问题第一件事都是打开这个文件看argv指向的解释器路径对不对。把这条路走通后面遇到的大部分内核问题你都能自己解决。2. 添加内核前的准备创建conda环境并装好ipykernel2.1 创建conda环境Python版本尽量显式指定假设你要给一个新的深度学习项目建一个环境通常的做法是conda create -n myenv python3.10 conda activate myenv很多人会图省事只写conda create -n myenv这样conda会用默认版本创建环境里可能是个很新的Python。本身没问题但容易埋雷比如项目里某个第三方库还没适配最新的Python版本或者你在网上抄的教程用pip install装包装出来的包跟当前解释器版本不兼容。所以我建议创建环境时显式指定Python版本尤其是当你需要在多个环境之间切换、并且给每个环境都加内核的时候写一个明确的版本号后面看内核列表也能一眼认出每个环境对应什么版本。创建环境时也不建议一次性装一大堆包保持环境干净。等环境建好、激活之后再按需安装ipykernel和项目依赖。一个环境里包装得多而杂正是后面各种奇怪冲突的根源。2.2 为什么每个要加内核的环境都得装ipykernel这一步是很多人忽略的关键。添加内核时执行的注册命令是python -m ipykernel install而这个命令本身是ipykernel提供的。也就是说你的目标环境里必须先装好ipykernel才能往jupyter notebook里注册内核。在激活后的环境里执行conda install ipykernel # 或者用pip pip install ipykernel装完可以顺手验证一下python -c import ipykernel; print(ipykernel.__version__)为什么必须是ipykernel因为jupyter notebook的通信协议叫Jupyter Messaging ProtocolPython解释器本身并不会说这个协议需要ipykernel充当翻译官。没有ipykerneljupyter notebook就算找到了你的Python解释器也没办法跟它对话。这一点在后面讲nb_conda_kernels自动发现方案时同样成立——它只是帮你把已经装好ipykernel的环境扫描出来并不会帮你把ipykernel安装到目标环境里。新手最容易踩的坑就是在base环境里执行了一堆安装命令然后发现其他环境的内核根本没生成。原因很简单注册命令必须要在目标环境中执行。记住这个顺序建环境 → 激活环境 → 装ipykernel → 注册内核。四步缺一不可。3. 添加内核的三种实操方法手动注册、自动发现、venv方案3.1 方法一ipykernel手动注册最通用也最可控手动注册是使用频率最高的方法命令就一条但参数值得逐个说清楚python -m ipykernel install --user --name myenv --display-name Python (myenv)各参数含义--name内核内部唯一名字用作内核目录的文件夹名也用于jupyter kernelspec系列命令定位。建议跟conda环境名保持一致否则时间久了会分不清谁是谁。--display-name显示在jupyter notebook界面的New菜单里的名字可以随便起中文英文都行比如 深度学习 (py310)。如果省略这个参数很多时候默认显示成Python 3这也是为什么有人装了多个内核却看到好几个同名选项。强烈建议每次都写清楚。--user安装到当前用户目录下不需要管理员权限这也是我推荐的方式。不加这个参数会默认装到系统级目录通常需要管理员权限还可能污染全局配置。执行完可以用下面这条命令确认是否安装成功jupyter kernelspec list输出里会出现类似Available kernels: python3 /home/user/miniconda3/share/jupyter/kernels/python3 myenv /home/user/.local/share/jupyter/kernels/myenv看到myenv这一条说明注册成功。回到jupyter notebook界面刷新浏览器点New新内核就会出现在列表里。注意如果你在执行注册命令之前忘了conda activate myenv那注册出来的内核指向的是当前激活环境很可能是base的Python不是myenv。因为这条命令会把当前环境的Python解释器路径原样写进kernel.json。顺序错了后面全错。3.2 方法二nb_conda_kernels自动发现所有conda环境如果机器上conda环境特别多一个个人工注册确实麻烦。这时候可以装nb_conda_kernels一次配置自动发现所有环境。安装方式conda activate base conda install nb_conda_kernels然后重启jupyter notebook。之后你打开New菜单会发现所有已经装了ipykernel的conda环境都自动出现在列表里不需要逐个手动注册。它的原理是nb_conda_kernels在启动时扫描机器的conda环境列表对每个环境检测是否存在ipykernel存在的话就为它动态生成一个内核入口。所以前面强调的目标环境要装ipykernel在这里依然成立nb_conda_kernels只是省去了你手动执行注册命令这一步。使用时的几个注意点它得装在base环境里因为jupyter notebook一般在base环境启动。自动生成的内核显示名会带环境信息类似 Python [conda env:myenv]跟手动注册的名字风格不太一样但功能一样。如果刚刚往某个环境里装了ipykernel而jupyter notebook是之前启动的需要重启jupyter notebook才能扫到新环境。这个看不见的坑非常常见后面排查章节还会提到。3.3 方法三virtualenv/venv环境添加内核不用conda、用Python自带的venv或virtualenv管理环境的人也不少。venv环境添加内核的原理跟conda完全相同只是环境创建和激活的命令变了# 创建虚拟环境 python -m venv myvenv # 激活Linux/macOS source myvenv/bin/activate # 激活Windows myvenv\Scripts\activate # 安装ipykernel并注册内核 pip install ipykernel python -m ipykernel install --user --name myvenv --display-name Python (myvenv)这里唯一需要注意的是venv创建的Python版本取决于执行python -m venv时用的那个python命令对应的版本。如果想创建不同Python版本的环境用conda会更省心或者直接安装对应版本的Python解释器再建venv。virtualenv在Python 3.3之后基本被venv取代还在用老一套mkvirtualenv的话迁到python -m venv会更干净添加内核的流程完全一致。三种方法用下来可以这么选方法适用场景优点缺点ipykernel手动注册任何环境通用性最强每个环境独立配置可控性好环境多时操作繁琐nb_conda_kernelsconda环境特别多自动扫描一次性配置只支持conda环境里仍需装ipykernel改动环境后要重启venv/virtualenv不用conda的Python项目轻量Python内置多Python版本切换不够方便4. 内核日常管理查看、删除和改显示名4.1 用jupyter kernelspec list查看当前所有内核内核数量一多就很容易忘记到底给哪些环境加过内核尤其是时间一长有些环境都删了内核还残留在列表里。查看所有已安装内核最简单的方式是jupyter kernelspec list这个命令会列出当前用户和系统级的所有内核格式大致是Available kernels: python3 /home/user/miniconda3/share/jupyter/kernels/python3 myenv /home/user/.local/share/jupyter/kernels/myenv oldproject /home/user/.local/share/jupyter/kernels/oldproject左边是内核内部名右边是对应kernel.json所在目录。看到这个列表你对全局内核情况就一目了然了。如果某个环境已经很久不用可以考虑删掉对应内核免得New菜单里堆太多选项看着乱选起来也容易错。4.2 删除内核、改显示名的正确操作删除内核的命令jupyter kernelspec remove myenv # 或者 jupyter kernelspec uninstall myenv两条命令等价uninstall是remove的别名。执行后对应的内核目录会被整个删掉包括里面的kernel.json。如果你只是想让内核从jupyter界面消失但保留conda环境本身用这个命令就对了。有些老教程教人手动删目录rm -rf ~/.local/share/jupyter/kernels/myenv虽然也能达到目的但用命令更安全命令会先检查内核是否存在避免手滑删错目录。手动删除只建议留给某些极端情况比如内核目录损坏、命令删不掉的时候。至于改显示名官方没有提供改名命令。想改的话有两种方式一是直接编辑内核目录里的kernel.json改display_name字段然后重启jupyter notebook二是删掉旧内核重新执行一次注册命令在--display-name里写新名字。比起手动编辑json文件我更推荐后者至少不容易把格式改坏。4.3 环境删了但内核还在清理步骤这里有个很典型的场景你在某个conda环境里做完实验环境不要了执行conda env remove -n myenv删掉了环境但jupyter notebook的New菜单里还留着 Python (myenv)。这时候如果点它notebook会直接报错因为内核配置里指向的Python路径已经不存在了。正确的清理顺序是先删内核再删环境或者至少记得删完环境之后把对应内核也删掉# 1. 删除内核 jupyter kernelspec remove myenv # 2. 删除conda环境 conda env remove -n myenv如果你已经先删了环境再执行jupyter kernelspec remove myenv也能删掉残留内核因为它删的是内核目录不依赖环境是否存在。这个坑虽然小但遇到时确实容易懵。把它想明白之后就清楚了内核属于jupyter notebook的配置资产跟环境本身的生命周期是两件事清理时要分开对待。5. 踩坑实录内核不显示、执行没反应、包导入失败的完整排查链路5.1 添加了内核但jupyter notebook里看不到这是最高频的问题了。添加内核命令执行成功jupyter kernelspec list也能看到但浏览器里的New菜单就是找不到。很多人以为没装上开始重装。实际上九成情况是下面三个原因之一第一jupyter notebook是在添加内核之前启动的。内核列表在notebook启动时读取一次之后不会自动刷新。解决办法是关掉浏览器页面重新启动jupyter notebook注意是重启进程不只是刷新页面。第二注册时用了--user但启动jupyter notebook的进程用户或权限不同。比如你在root用户下注册了内核再用普通用户启动jupyter notebook自然看不到。解决方式是统一用户或者装到系统级目录注意权限。第三浏览器缓存。内核确实装了界面还停留在旧页面强制刷新一下CtrlShiftR / CmdShiftR就好。如果上面三步都试完还是不行就从jupyter kernelspec list的输出路径里找到对应的kernel.json打开看argv里的路径是否真实存在。不存在就说明注册时记录的环境已经变了重新激活目标环境再注册一次。5.2 单元格执行代码没有任何反应进度条一直转这个症状也很常见点运行单元格旁边出现In [*]然后一直转圈既没有输出也没有报错。这基本是内核连接层面的问题。第一件事不是重装而是去看启动jupyter notebook的那个终端窗口里面通常会有内核崩溃的错误日志。最常见的原因有这么几类ipykernel版本与Python版本不兼容。比如Python 3.12配了非常老的ipykernel启动时直接崩溃。解决方式是在目标环境里执行pip install --upgrade ipykernel。环境里的某个包导致内核启动阶段崩溃。比如你配置了~/.ipython/profile_*下的启动脚本或者装了会在解释器启动时自动加载的包。排查方式是在终端手动执行python -c import ipykernel如果这一步就报错说明环境本身有问题跟jupyter notebook无关。连接文件权限问题。在远程服务器或者docker容器里跑的时候{connection_file}指向的临时目录没权限读写内核连接不上。这种情况检查jupyter启动时的临时目录权限即可。还有一个容易被忽略的原因你点运行的时候内核其实处于重启中或半死状态旧内核没完全退出新内核又起不来。遇到这种情况在Kernel菜单里选Restart Kernel或者干脆在终端里CtrlC停掉整个jupyter notebook再启动。排查这类问题我建议按看终端日志 → 手动在目标环境测试ipykernel → 检查kernel.json路径 → 重启jupyter的顺序走不要一上来就卸载重装。大多数执行无反应的内核问题根因都是环境里的Python解释器启动不起来了jupyter notebook只是被连累而已。5.3 内核能跑但import包报ModuleNotFoundError这个场景同样极高频在notebook里import numpy或者import torch提示ModuleNotFoundError但你在终端conda activate myenv之后执行同样的import却成功。几乎所有这类问题都指向同一个原因内核连的Python解释器跟你以为的那个环境不是同一个。也许你在base环境创建了notebook然后在内核选择器里选了个旧内核也许你之前在别的环境里注册过一个同名内核也许你用nb_conda_kernels时目标环境里ipykernel没装它实际给你起了另一个兜底环境。最快的定位方法是在notebook里先执行这句import sys print(sys.executable)它会打印当前内核实际使用的解释器路径。只要确认了这个路径问题就好办了路径不是你目标环境的Python → 内核选错了或者kernel.json里的argv写错了重新编辑配置文件或重新注册。路径是你目标环境的Python → 说明包确实没装进这个环境。激活对应环境重新安装缺失的包。路径是base环境的Python但你希望在myenv里跑 → 说明notebook里选的内核是旧的 Python 3 而不是 Python (myenv)。有人看到两个名字长得像随手点了上面那个就以为环境没生效。提示用pip给conda环境装包时建议在激活该环境后执行python -m pip install 包名不要直接敲pip install 包名。前者保证pip跟当前使用的解释器绑定后者在某些环境组合下会指向系统级的pip导致包装错地方。6. 延伸场景VSCode切换内核、远程服务器添加内核与几个实用习惯6.1 VSCode里切换内核和添加配置现在很多人不用浏览器版jupyter notebook直接在VSCode里打开.ipynb文件。VSCode的Jupyter支持同样基于内核机制所以前面学的所有内核管理命令在VSCode里完全通用。VSCode切换内核的操作打开一个.ipynb文件右上角会显示当前内核名称比如 Python 3 (ipykernel)点击它弹出内核选择列表里面会列出所有已安装的内核和可用的Python环境选一个就行不需要额外配置。如果你在VSCode的内核列表里看不到某个conda环境先检查那个环境里是否装了ipykernel。VSCode会扫描Python环境但能否作为Jupyter内核使用还是取决于环境里有没有ipykernel这一点跟浏览器版jupyter notebook没有区别。这里要单独提醒一个坑VSCode左侧命令面板里的 Python: Select Interpreter搜索 Python: Select Interpreter控制的是普通.py文件的解释器而.ipynb文件的内核选择是另一个独立入口。很多人在VSCode里折腾半天以为选了Python解释器就能让notebook用上这个环境其实两者是两套选择器。这个点跟vscode python环境配置这个话题经常一起被问到所以单独拎出来说一下。6.2 远程Linux服务器上的内核添加流程如果你有一台远程服务器上面跑着jupyter notebook服务想在本地浏览器里访问同时还能正常切换内核大概要做两件事搞定网络连接和注册内核。网络连接最方便的方式是SSH端口转发ssh -L 8888:localhost:8888 用户名服务器地址然后在服务器上启动jupyter notebook --no-browser --port8888本地浏览器访问http://localhost:8888就能打开服务器上的jupyter notebook。本质是把本地的8888端口映射到服务器的8888端口在本地点开的页面实际请求都在服务器上执行。内核添加方式跟本地一模一样但要注意两点第一在服务器上添加内核时kernel.json里的路径是服务器上的绝对路径比如/home/user/miniconda3/envs/myenv/bin/python。如果你用本地路径去套或者在不同服务器之间直接复制kernel.json路径对不上内核肯定起不来。我在多台服务器之间迁移环境时就经常因为忘了改路径而多花半小时。第二无桌面版的Linux服务器没法开浏览器看界面但jupyter kernelspec list这类命令完全通用排查思路也跟本地一致。6.3 我给内核做日常维护的几个习惯最后分享几个长期使用下来比较顺手的习惯不算什么高深技巧但确实帮我少踩了很多坑。第一每次新建conda环境后不管当下用不用先把ipykernel装好、把内核注册掉。免得过几天要用的时候环境建了、包装了却忘了当初的内核名叫什么、指向哪里。第二--display-name里尽量带Python版本号或项目名比如 nlp-py310、项目A-prod。环境多了之后New菜单里每个名字对应哪个项目、哪个版本一眼就能分清省下大量回忆时间。第三删除环境之前先执行jupyter kernelspec remove 对应名字再执行conda env remove。把内核这个配置资产和环境本身分开管理清理的时候就不会留下残渣。第四遇到任何内核问题第一步看启动日志第二步在notebook里打印sys.executable。这两步能定位绝大部分问题比反复卸载重装高效得多。这些习惯听起来简单但真遇到问题的时候它们就是整个排查链路里最快的切入点。