Windows 安装 Jupyter Notebook：环境、内核与排错

Windows 上装 Jupyter Notebook表面上就是敲一行命令的事真正动手过的人都清楚坑基本都集中在前面那五分钟Python 装完pip认不出来、命令窗口里jupyter提示“不是内部或外部命令”、浏览器打开是一片空白、好不容易进去了却发现自己装的库在 Notebook 里 import 不到。这些问题单看都不难但凑在一起足够让一个刚上手的人卡掉整个下午。这篇内容就是把这些年我在 Windows 上反复装、反复给同事配环境的经验整理出来从解释器选型、pip 源配置、虚拟环境隔离到启动参数、内核注册、常见报错排查一步一步写清楚每个选择背后为什么这么做也一并说明。它不是什么官方文档的翻译而是一份可以直接照着敲、敲完就能跑的实操记录适合刚接触数据分析或科学计算的新手也适合已经用过 Notebook 但环境总是装不明白的老用户对照着检查一遍。1. 动手之前先想清楚Jupyter Notebook 到底装的是什么很多人对这件事的误解在于以为 Jupyter Notebook 是像 Word 一样双击安装的软件。它其实不是它是一套跑在 Python 环境里的服务端程序你敲的jupyter notebook命令启动的是一个本地小型 Web 服务然后浏览器去访问这个服务你在网页里写代码、点运行代码通过一个叫 Kernel 的后台进程真正执行结果再回传渲染到页面上。搞清楚这条链路后面遇到的九成问题都能自己定位浏览器打不开是服务没起来或端口被占代码跑不动是 Kernel 挂了import 失败是 Kernel 用的解释器和你装包的解释器不是同一个。1.1 为什么它值得单独装一套环境Notebook 的核心价值是把“写代码—看结果—改代码”这个循环压缩到几乎零成本。传统写法是编辑器里改一行、切到终端跑一次、再切回来看输出来回切窗口本身就把思路打断了Notebook 的单元格机制让你在同一个页面里分段执行中间结果留在内存里画个图直接显示在代码下面写分析报告的时候文字和代码可以混排最后导出一份 HTML 就能直接发给别人看。这种交互方式特别适合数据探索、模型调参、教学演示这类“边试边看”的场景。但它也有代价。Notebook 的执行顺序是可以乱来的你可以先跑第 5 个单元格再跑第 2 个这就导致同一个文件在不同人手里跑出来的结果可能不一样做工程化项目的时候这是硬伤。我的做法是把 Notebook 定位成“草稿纸和演示台”正式代码还是落在.py文件里Notebook 只负责验证想法和出图。理解这个定位你就不会纠结“为什么我的 Notebook 跑得好好的部署上去就崩了”——因为它本来就不是干这个的。1.2 三条安装路线各自适合什么人Windows 上装 Jupyter 有三条主流路线选错了不会报错但会在后面持续给你添堵所以这一步值得花两分钟想清楚。路线核心命令优点缺点适合人群纯 pip 安装pip install notebook轻量只装必要组件环境干净可控需要自己管好 Python 和 PATH已有 Python 基础、想精确控制环境的人发行版全家桶安装打包好的科学计算发行版开箱即用numpy/pandas 一次到位体积大装的东西多环境容易变“重”完全新手、不想折腾依赖的人虚拟环境 pippython -m venv后 pip 安装隔离彻底多个项目互不污染多一步激活操作新手容易忘有多个项目、需要长期维护环境的人我个人的选择是第三条而且强烈建议你也走这条。原因很简单你不可能只做一个项目也不可能所有项目都用同一套依赖版本。全局装一次看着省事等到某天两个项目要的库版本打架你就要花半天去拆环境那个代价远比每次多敲一行激活命令高。2. 环境准备Python 与 pip 的检查与配置这一节是整篇内容里最容易被跳过、也最容易出问题的部分。很多人装完 Python 就直接pip install然后卡在“命令找不到”上。Windows 的 PATH 机制决定了安装时少勾一个选项后面就要手动补环境变量与其事后折腾不如装的时候就一次到位。2.1 装 Python 时那个必须勾选的选项去 Python 官方站点下载 Windows 安装包版本上建议选 3.10 或 3.11 这一类已经非常成熟的版本不要一上来就追最新。原因在于科学计算生态里的某些库对最新版本的解释器适配会滞后你可能装完发现某个依赖编译不过其实是版本太新导致的。3.9 以下也不建议一些新版本的 Notebook 已经不再支持。安装界面第一屏底部有两个复选框一个是Install launcher for all users另一个是Add Python to PATH。第二个必须勾上这是整篇教程里最重要的一次点击。勾上之后安装程序会把 Python 的安装目录和 Scripts 目录写进系统环境变量你才能在任意位置的命令窗口里直接敲python和pip。如果忘了勾症状就是命令窗口里提示找不到命令解决办法要么是重新运行安装包选 Repair 并补勾要么是手动去“系统属性—环境变量”里加两条路径后者对新手来说更容易出错。还有一点值得提醒安装路径里不要带中文和空格。有些人习惯把软件装到D:\我的软件\Python\这种位置表面上能装成功但后续某些依赖在编译或者调用时对路径编码处理不好会抛出莫名其妙的解码错误。稳妥的做法是用纯英文、无空格的路径比如D:\Dev\Python311\。2.2 验证安装与 pip 源的正确配置方式装完之后不要急着往下走先开一个新的命令窗口做验证。这里强调“新的”是因为环境变量的修改对已经打开的窗口不生效很多人装完发现命令还是找不到就是因为用的是安装前就开着的那个窗口。python --version pip --version where python where pip四条命令逐条看结果。前两条输出正常说明命令能识别重点看后两条它们会打印出实际调用的可执行文件路径。如果where python打出来不止一条说明你机器上装了多个 Python这时候就要注意pip装到哪个环境去了这是后面“装完库 import 不到”的头号元凶。接着配置 pip 源。默认源在国外装 Notebook 这种依赖比较多的包下载速度可能慢到怀疑网络。配置国内镜像站能明显改善体验但要注意镜像站的地址会变我这里用一个占位写法你按实际拿到的地址替换即可。python -m pip config set global.index-url https://镜像站域名/simple python -m pip config set global.trusted-host 镜像站域名第二条命令在部分环境下是必需的因为镜像站如果走 HTTP 或者证书链不完整pip 会拒绝下载并报 SSL 相关错误加上 trusted-host 就绕过了这个校验。这个操作会写进用户目录下的 pip 配置文件只对当前用户生效不会污染系统。想确认写没写进去用python -m pip config list看一眼就行。2.3 虚拟环境为什么每次都该建一个新的虚拟环境的本质是在项目目录下复制一份独立的 Python 解释器和site-packages目录激活之后所有pip install都装进这个副本里跟全局环境完全隔离。打个比方全局环境是公共厨房谁都能进去改调料摆放虚拟环境是给你单独开的小灶你怎么折腾都不影响别人。创建和激活的命令如下注意路径别写中文cd D:\Dev\projects\notebook-demo python -m venv .venv .venv\Scripts\activate.bat如果你用的是 PowerShell 而不是传统命令提示符激活脚本是.venv\Scripts\Activate.ps1这时候很可能遇到一堵墙无法加载文件 ...Activate.ps1因为在此系统上禁止运行脚本这不是环境坏了是 PowerShell 默认的执行策略比较保守。解决办法是给当前用户放行本地脚本Set-ExecutionPolicy -Scope CurrentUser RemoteSignedRemoteSigned的意思是本地写的脚本可以跑从网上下载的脚本需要签名。这个粒度比直接设成Unrestricted安全得多别图省事用后者。设置完重新执行激活脚本你会看到命令行提示符前面多了一对括号里面是环境名这个视觉提示很重要它告诉你现在所有操作都作用在这个沙箱里。3. 正式安装从一条命令到浏览器里的第一个单元格环境准备好之后安装本身确实就是一条命令。但这条命令背后装了什么、装完之后怎么启动、启动之后那个带 token 的地址是怎么回事这几件事值得说清楚否则下次换台机器你还是一脸茫然。3.1 安装命令与背后装了什么在已激活的虚拟环境里执行python -m pip install --upgrade pip python -m pip install notebook第一行是先升级 pip 自己。这一步经常被忽略但老版本 pip 在解析依赖关系时能力较弱遇到复杂的依赖树可能给你装出一套版本互相冲突的包或者干脆解析失败。升级成本很低养成习惯就好。第二条命令会拉下来一串依赖比较关键的几个jupyter-core负责任务调度和路径管理jupyter-client负责和 Kernel 通信ipykernel是 Python 的默认内核nbformat负责.ipynb文件的读写tornado是底层的 Web 服务框架。你会注意到notebook这个包本身很小大部分体量都在这些依赖上这也是为什么它不能用“绿色版解压即用”的方式分发。安装过程中如果看到一大片红色的ERROR先别慌往上翻找到真正的失败原因那一行。常见的是网络超时换源解决、某个包需要编译但没有对应工具链通常是版本太新降一个版本即可、以及权限不足说明你在往系统目录装回到虚拟环境里操作。装完验证一下python -m pip show notebook jupyter --version第二条命令会打印出各个组件的版本号能看到notebook、jupyter_core、ipykernel几行就说明装齐了。3.2 启动、端口与 token 登录机制在项目目录下直接敲jupyter notebook正常情况下命令窗口会刷出一串日志最后停在一个类似http://localhost:8888/tree?token一长串字符的地址上浏览器会自动弹出来。如果没有自动弹手动把这个地址完整复制到浏览器里注意一定要带上 token 那一段只输入localhost:8888是进不去的。这个 token 是一层本地安全防护。因为 Notebook 的服务本质上是监听在本机端口上的一个 Web 应用如果不加验证同一局域网里的其他人构造个请求就能在你的机器上执行任意代码。token 就是防止这个的。缺点是每次启动都变复制起来烦。可以用密码替代jupyter notebook password按提示输入两遍密码它会写进用户目录下的jupyter_server_config.json。之后启动就可以直接输密码登录token 那串东西不用再管了。密码别设太简单虽然只在本机监听但如果你改过配置让它对外提供服务弱密码就是明摆着的口子。关于端口默认是 8888。如果这个端口已经被别的程序占了——比如你之前启动过没关掉或者装了什么别的开发工具——Jupyter 会自动往后找一个空闲端口日志里会显示 8889、8890 之类。想确认到底谁占了 8888netstat -ano | findstr :8888拿到最后一列的进程号再去任务管理器里对一下把占用的进程关掉就行。3.3 内核是什么以及怎么让 Notebook 用上别的 Python这是新手最容易懵的概念。你把 Notebook 理解成一个“遥控器”Kernel 是被遥控的那台“电视”。遥控器只负责发指令和显示画面真正干活的是电视。所以当你在 Notebook 里import pandas报错说找不到模块时问题几乎百分之百不在 Notebook而在于那个 Kernel 用的 Python 环境里没有 pandas。默认情况下jupyter notebook启动时用的 Kernel 就是你启动它的那个 Python 环境。这在虚拟环境里是符合预期的。但如果你机器上有多个 Python比如一个 3.9 一个 3.11想在一个 Notebook 界面里切换就需要手动注册内核python -m ipykernel install --user --name py311 --display-name Python 3.11--name是内部标识只能用小写英文和短横线--display-name是界面上显示的名字可以写中文。执行完之后重启 Notebook在右上角或者Kernel菜单里就能看到新的选项。想清理掉不用的内核jupyter kernelspec list jupyter kernelspec remove py311第一条列出所有已注册内核及其配置文件路径第二条按名字删掉。这个清理动作值得定期做尤其是你反复建删虚拟环境之后会残留一堆指向已经不存在路径的内核界面上选到这种内核就是一个Kernel died之类的错误。4. 配置文件与常用参数调整命令行参数只在当次启动有效想长期生效就得改配置文件。Jupyter 的配置体系分两层旧版叫jupyter_notebook_config.py新版基于 Jupyter Server 的叫jupyter_server_config.py两者的键名前缀不一样。版本迭代过程中这块变动比较频繁直接手写很容易踩空稳妥的做法是先让程序生成一份带完整注释的默认配置再改自己关心的那几行。4.1 生成配置并改掉默认工作目录jupyter notebook --generate-config它会在用户目录下的.jupyter文件夹里写一份配置文件路径会打印在输出里。用任意文本编辑器打开里面几乎全是注释掉的示例搜关键词比从头读效率高得多。最常改的是启动时的工作目录。默认它会定位到用户主目录而你的项目在 D 盘某个文件夹里每次启动都要手动点进去很烦。老版本搜c.NotebookApp.notebook_dir新版本搜c.ServerApp.root_dir找到后取消注释把值改成目标路径注意 Windows 路径的反斜杠要转义或者直接用正斜杠c.ServerApp.root_dir D:/Dev/projects/notebook-demo另外两个常改的一个是c.ServerApp.port把默认端口固定下来避免每次都是新端口导致收藏夹里的地址失效另一个是c.ServerApp.open_browser设成False就不会自动弹浏览器适合习惯自己开窗口的人。注意改配置文件时缩进和引号必须严格符合 Python 语法哪怕只少一个引号启动时也会直接抛语法错误。改完先存盘再敲一次启动命令验证别一次改十处然后不知道哪处错了。4.2 插件与主题锦上添花而非必需装完基础环境之后很多人会想加点插件提升体验。比较有名的是提供代码折叠、目录树、变量检查的扩展集合python -m pip install jupyter_contrib_nbextensions jupyter contrib nbextension install --user装完重启界面上会多一个扩展管理标签页里面勾选需要的功能即可。不过这里要说句实话如果你只是日常写写分析代码原生功能完全够用装插件反而会拖慢启动速度而且部分扩展在新版本 Notebook 上兼容性并不好装了之后整个界面白屏的情况我遇到过不止一次。我的建议是先裸用一段时间真觉得某个操作反复打断你再去针对性装那一个扩展别一上来就全勾上。主题同理。默认界面是白底长时间看确实累眼但改主题的包往往是靠注入自定义 CSS 实现的版本一升级就可能错位。如果确实需要优先用浏览器自带的深色模式插件或者 Notebook 较新版本自带的主题设置别去动核心样式文件。4.3 几个真正提升效率的内置能力比起外挂插件Notebook 自带的一些机制价值更高但很多人不知道。单元格执行顺序混乱是 Notebook 的老毛病解决办法是养成固定习惯每次重新打开文件先执行Kernel — Restart Run All从头跑一遍。这样能立刻发现隐藏的依赖顺序问题。如果某个单元格跑得特别慢用魔法命令计时%%time # 这里放你要测的代码块双百分号作用于整个单元格单百分号只作用于紧跟着的一行。想看某个函数内部每行的耗时用%prun或者%lprun。这些都属于定位性能问题时的第一手工具比事后猜要靠谱得多。还有一个我几乎每次都会开的自动重载。写模块化代码的时候你在.py文件里改了实现Notebook 里 import 进来的还是旧版本手动重启内核很打断节奏。%load_ext autoreload %autoreload 2%autoreload 2的级别是“每次执行单元格前重新加载所有已经 import 的模块”比级别 1 更彻底。代价是稍微慢一点点但对开发调试来说完全值得。5. 常见问题排查实录下面这些是我在别人的机器上、也在自己机器上反复遇到的真实情况按发生阶段归类配上定位思路。排查的核心原则只有一条看错误信息的第一行和最后一行。第一行通常告诉你哪个环节出了问题最后一行是具体的异常类型中间那一大坨调用栈多数时候是给开发者看的不用逐行读。5.1 安装阶段命令找不到与依赖冲突现象最可能的原因处理方式pip 不是内部或外部命令Python 安装时没勾 Add to PATH或当前窗口是安装前打开的关掉重开窗口仍不行则修复安装补勾选项jupyter 不是内部或外部命令装在别的环境里了当前环境没装python -m jupyter --version确认用python -m pip install notebook重装下载到一半卡住或超时默认源网络不稳换镜像源加长超时--timeout 60某个包编译失败版本太新缺少预编译轮子指定稍低的版本号重装PermissionError往系统目录装权限不足回到虚拟环境里操作或加--user重点说第二条。很多人遇到jupyter命令找不到第一反应是重装结果重装完还是不行因为压根没搞清楚装哪去了。判断方法很简单在同一个窗口里先后执行python -m pip show notebook和jupyter --version前者能输出信息说明包在后者报错说明 Scripts 目录不在 PATH 里。这时候用python -m jupyter notebook大概率能启动因为-m是让 Python 自己去模块路径里找绕过了 PATH。这只是权宜之计长期还是要修好环境变量。5.2 启动阶段浏览器打不开与端口占用浏览器一片空白、一直转圈、或者提示无法访问此页面这几类问题的排查顺序是固定的。先看启动命令的那个窗口。它必须一直在运行关掉窗口服务就没了浏览器自然打不开。这个道理简单但真有人以为启动完之后窗口可以关掉。窗口关掉之后服务就随之中止页面刷新就会提示连不上。再看地址对不对。localhost和127.0.0.1是等价的但如果你手动改成了机器名或者局域网 IP可能因为防火墙规则访问不到。先在启动窗口里找到它自己打印的那一整个 URL原样复制别自己拼。token 那一段如果漏了会被重定向到登录页如果我密码和 token 都不记得最干脆的办法是删掉用户目录下.jupyter文件夹里的配置和密码文件重新生成一次。端口占用的表现是窗口里有日志但你访问 8888 打不开因为服务其实跑在 8889。这时候看日志里打印的地址里面端口号是多少就访问多少。想彻底固定下来在配置里写死端口或者启动时加参数jupyter notebook --port 8890。提示如果你在公司的办公电脑上操作某些安全软件会拦截本地端口的监听表现为启动瞬间闪过一行日志然后进程退出。这类情况建议先临时关闭相关防护再试确认是拦截导致之后再把 Jupyter 的进程加入白名单不要长期关闭防护。5.3 运行阶段内核挂掉与模块导入失败Kernel died或者内核不断自动重启这类问题排起来相对麻烦因为错误发生在子进程里主窗口的日志信息有限。第一件事是看启动窗口有没有输出。内核崩溃的堆栈会打在启动的那个窗口里而不会显示在浏览器页面上很多人只盯着浏览器看自然什么都找不到。找到堆栈之后常见的两个原因一是内存不够加载了个大文件把进程撑爆了解决办法是缩小数据量或者换 64 位的解释器二是某个 C 扩展的依赖缺失报错里一般会有.dll找不到之类的字样装对应的运行库即可。比崩溃更常见的是“装完库了但 import 不到”。前面提过根因几乎都是环境错位。验证方法是在 Notebook 单元格里跑一段import sys print(sys.executable)打印出来的路径应该和你激活虚拟环境之后在命令行里执行where python的第一条路径完全一致。如果不一致说明这个 Kernel 指向的是另一个 Python。这时候要么换内核要么在正确的环境里重装包。还有一种情况是你在 Notebook 里用了!pip install xxx这种感叹号开头的方式装包这种方式调用的是系统 pip 而不是当前内核的 pip装完照样 import 不到这个坑相当隐蔽。最后一个高频问题文件路径里的中文。读取本地数据文件时用了带中文的路径报编码错误或者文件不存在。稳妥的做法是数据文件统一放纯英文目录或者在代码里用pathlib处理路径它对编码的处理更规范。如果实在避不开中文路径读取文件时显式指定encodingutf-8虽然这解决不了所有场景但能覆盖大部分文本读取的情况。6. 一套可以直接抄的环境维护习惯装完能跑只是起点真正决定你这套环境能不能长期用下去的是后续的维护方式。我见过太多人第一次装得很顺几个月后想加个新库结果一装就把整个环境搞崩然后只能推倒重来。这部分分享几个我一直在用、成本很低但效果明显的习惯。第一每个项目一个环境环境名和项目目录同名。这听起来啰嗦但你半年后回头看一堆venv1、venv2、test根本分不清哪个是哪个。我现在统一在项目根目录下建.venv靠目录本身标识激活脚本路径固定复制项目的时候顺手把环境一起带走或者删掉重建不会混淆。第二把依赖清单导出成文件跟着项目一起存。在环境激活状态下执行python -m pip freeze requirements.txt以后换机器或者重装一条python -m pip install -r requirements.txt就能还原。这个文件要提交到版本管理里但注意freeze会把所有间接依赖都列上版本锁得很死这在保证可复现性上是优点在需要升级时就显得笨重。我的折中是维护两份一份锁定版用于还原一份只写直接依赖的宽松版用于升级时参考。第三定期清理内核注册表。虚拟环境删了但注册过的内核条目还在界面上选到就是个错误。前面提过用jupyter kernelspec list查、remove删养成每个月扫一眼的习惯。同理pip 缓存也会越积越大偶尔跑一次python -m pip cache purge释放空间。第四别在生产用途上直接依赖 Notebook 文件。导出成.py是个好习惯菜单里就有这个功能但导出之后的代码结构往往很乱需要手动整理。我的做法是探索阶段全在 Notebook 里一旦某个逻辑稳定下来就把它抽到独立的模块文件里Notebook 里只留调用和数据展示。这样既保留了交互调试的便利又不至于让整个项目变成一堆没法测试的单元格。第五备份配置文件。改好的jupyter_server_config.py和密码文件都在用户目录的.jupyter文件夹下换机器的时候把整个文件夹拷过去新环境直接就是熟悉的配置省掉重新调一遍的功夫。这个文件夹不大但里面可能有你的访问密码拷到别处之后记得别随手传到公开的地方。我在实际配置中还有一个体会不要把环境配得太“顺手”。看起来矛盾但道理是这样的——你给环境加了太多自动化的钩子、太多默认加载的扩展、太多全局生效的配置一旦某个环节升级不兼容排查起来会非常痛苦因为你根本不知道是哪一层在起作用。我现在倾向于保持基础环境尽可能素需要什么就在具体项目里加什么出问题的时候变量少定位快。装 Jupyter 这件事本身也是如此先把最小可用的一套跑通用上一段时间遇到真实痛点再去补比一上来照着各种“必装清单”全配一遍要踏实得多。