Jupyter Notebook升到7.0.0之后老一套汉化和改路径的方法突然全失灵了。问我的人比平时翻了好几倍问题集中在两个地方一是界面语言包装上之后没反应二是新建文件永远落在C盘用户目录下项目和文件散得到处都是。花了两天时间把v7整个翻了个底朝天把语言包机制、配置项变化、前后端关系都捋了一遍下面直接把能用的方案写出来。这篇东西适合所有被新版Notebook折磨过的用户不管你是刚升级上来还是准备重装照着做基本都能解决。1. 从旧版到v7到底哪里变了1.1 一次看起来是升级、实际是重构的版本迭代很多人以为Jupyter Notebook v7只是给旧界面换个皮肤这想法害了不少人。实际上Notebook 7是把原本独立的Classic Notebook界面彻底废弃改成了基于JupyterLab组件重新构建的单文档模式。说白了你在浏览器里看到的那个文件列表、编辑器、菜单栏底层全部变成了JupyterLab的东西。这个架构调整带来的直接后果是以前你搜到的那些针对Notebook 6.x写的汉化教程比如替换locale目录、修改linguist配置文件、往nbextensions里塞语言包在v7里全都废了。因为界面不再是旧的notebook前端而是JupyterLab的文档管理器在渲染了所以新的汉化方式必须跟JupyterLab的语言机制对齐。还有一点要注意Notebook v7和JupyterLab的版本是强关联的。Notebook 7.0.x对应的是JupyterLab 4.x的组件后面升级小版本时也会跟着同步更新。所以你装任何插件、语言包时必须清楚自己到底是在给哪个版本的语言体系装东西装混了就会出各种奇怪问题。1.2 变了的配置项从NotebookApp到ServerApp旧版配置里大家最熟悉的一行是c.NotebookApp.notebook_dir用来指定默认工作目录。到了v7这行配置在生成配置时你会看到设置项确实还在Jupyter也做了兼容但官方推荐的写法已经变成了c.ServerApp.root_dir。原因也好理解新版架构里真正干活的是Jupyter ServerNotebookApp只是它上面的一个应用外壳。你改NotebookApp开头的配置Jupyter Server读不读得到完全看运气我在好几个环境里实测过改了c.NotebookApp.notebook_dir之后配置文件依然会生效但有时会把工作目录设置到奇怪的地方不如直接用ServerApp稳。更坑的是新版生成配置文件的命令、路径、生效优先级跟旧版也有区别。很多人明明改了配置文件重启服务后一点用处都没有就是因为配置没写到Jupyter实际读取的位置或者被启动参数覆盖了。这个在第3节我会专门展开说。1.3 v7用户最容易踩的三个认知误区先说第一个误区认为汉化就是装个语言包。这话对一半语言包确实是新版汉化的核心但装完之后必须在界面里手动切换一次语言然后刷新页面。很多人在终端看到Language Pack installed就以为完事了结果打开还是英文就开始怀疑教程有问题。第二个误区认为改配置就是改一个文件的事。新版Jupyter的配置涉及jupyter_notebook_config.py、jupyter_server_config.py两份文件还有启动参数、环境变量、命令行中个优先级从高到低是启动参数 环境变量 配置文件 默认值。你不搞清楚当前配置到底是谁在生效就会陷入改了没用、删了也一样、折腾一晚上不知道原因的僵局。第三个误区认为所有环境共用一套配置。如果你用conda建了好几个虚拟环境每个环境里装的Jupyter版本可能完全不同。你在base环境里汉化好了切到另一个环境又变回英文这不叫失效是那个环境里压根没装语言包。做任何操作之前先激活对应的虚拟环境这个习惯比任何技巧都重要。2. 新版Jupyter Notebook汉化实操指南2.1 汉化前的版本检查与环境准备不要一上来就pip install先花一分钟确认你的实际环境。打开命令行输入下面三条命令把结果记下来python --version jupyter --version jupyter lab --version这里重点看两件事。第一你的Notebook版本到底是多少jupyter --version输出的最后一项会显示notebook的版本号如果低于7.0.0那你可能要怀疑自己升级是不是失败了。第二jupyter lab --version这个同样关键因为Notebook v7复用JupyterLab的语言插件体系语言包版本对不对要看这个。同时确认你的Python版本我推荐3.9到3.11之间跑Jupyter Notebook v7最省心。Python 3.12、3.13也能跑但后面讲到的rpds报错、pyzmq兼容问题大多出现在这两个新版本上。如果你急着用暂时不要用太新的Python跑生产环境。都确认好了再检查一下自己的Jupyter是从哪个环境启动的尤其是装了Anaconda、又用VS Code、又用系统Python的朋友。命令行里敲where jupyterWindows系统或者which jupytermacOS/Linux看清楚你接下来要操作的是不是同一条路径。很多人就是这里没注意在base环境装了一堆包然后从别的环境启动结果所有操作看着都做了、全都无效。2.2 安装中文语言包的核心操作在确认好目标环境后激活虚拟环境如果有的话执行这条命令pip install jupyterlab-language-pack-zh-CN这个包的名字带有jupyterlab前缀是因为前面说过的原因——Notebook v7的语言机制完全走JupyterLab这套。你不需要担心它是给JupyterLab用的装上它Notebook v7一样能读。如果提示已经安装了建议顺手升级一下pip install -U jupyterlab-language-pack-zh-CN安装完成后直接在终端重启Jupyter Notebook服务。注意是完整退出再启动包括关掉浏览器里所有相关的标签页。因为语言包是在服务启动阶段加载的热刷新解决不了问题。另外顺嘴说一句如果你的网络环境下载PyPI资源比较慢可以换用国内镜像源。我一般用清华源命令是pip install -i https://pypi.tuna.tsinghua.edu.cn/simple jupyterlab-language-pack-zh-CN装完不要急着打开先往下看界面设置这一步。2.3 在界面中激活中文语言语言包装好、服务重启后在浏览器打开你的Jupyter Notebook页面。这时候界面应该还是英文不要慌这是正常的。你要做的是进入语言设置界面位置在菜单栏的File - Settings - Language。进去之后会看到一个大下拉框里面列了一堆语言找到简体中文zh-CN或者直接显示为中文的选项选中它。如果这里只有English一个选项说明你的语言包没有成功被服务识别。这时候回到终端看一下启动日志里有没有报错最常见的错误是提示找不到jupyterlab-language-pack-zh-CN对应的资源那就重新执行一遍2.2的安装命令。选完语言后页面上通常会提示需要重启或者刷新。点击确认或者Reload按钮浏览器页面会重新加载。加载完之后菜单栏、右键菜单、设置面板这些核心区域应该已经变成中文了。装好之后你可能会发现有些地方还是英文比如插件设置里的说明、某些工具栏工具提示。这个很正常语言包对界面做了翻译但第三方插件、部分前沿组件、个别深层配置项没有翻译是正常的。你只要确认菜单和选项是中文就算汉化成功了。2.4 汉化后的界面状态与残留英文说明汉化完成后自查一下这几个地方文件列表上方的工具栏、菜单栏的File/Edit/View这些菜单、右键新建Notebook的菜单、Settings配置面板。这四个地方全部显示中文就是成功。有些细心的朋友会问那Notebook单元格的代码提示、命令面板CtrlShiftP里会不会也变中文命令面板里大部分会变成中文但有些来自内核和扩展的命令还是英文。比如你装了jupyterlab-git插件它的命令可能还是英文因为这个插件自身的语言资源和核心包不在一起。还有一点语言包是跟随环境的。你在base环境汉化好了换了conda虚拟环境又变回英文的话需要去对应环境里也安装并设置一次。这篇东西前面讲过这里再强调一遍因为这是问得最多的问题。3. 默认保存路径修改的完整方案3.1 搞清楚配置文件到底该改哪个默认保存路径的问题核心是理解Jupyter Notebook到底在哪个目录启动、新建的.ipynb文件默认存在哪。v7版本下,Jupyter启动目录由ServerApp.root_dir决定配置文件里的设置项长这样c.ServerApp.root_dir D:/JupyterProjects先执行命令生成配置文件如果你还没有的话jupyter notebook --generate-configWindows系统下配置文件位置一般在C:\Users\你的用户名\.jupyter\jupyter_notebook_config.pymacOS/Linux在~/.jupyter/jupyter_notebook_config.py。用记事本或任意编辑器打开搜索ServerApp.root_dir把前面的注释符号#删掉然后填入你希望作为默认工作目录的路径注意Windows下用正斜杠或者双反斜杠。这里有个容易翻车的点新版Jupyter还读jupyter_server_config.py这份文件也有root_dir配置。如果你的Notebook配置改了没生效十有八九是server配置里还残留着一个旧路径或者两份文件的设置相互打架。直接搜索用户目录下的.jupyter文件夹把两份配置文件都打开看一眼以ServerApp.root_dir为准统一修改。3.2 修改默认工作目录的两个层次默认路径修改其实要按场景区分一种是让Jupyter服务启动后文件列表停在指定目录另一种是新建文件后保存到指定目录。前者靠root_dir就能解决后者还需要配合浏览器里的文件保存习惯。设置root_dir之后你启动Jupyter浏览器左侧文件树打开的路径就是它。在这个目录下新建Notebook保存后文件就落在里面。如果你的需求只是别一打开就在C盘用户目录“改root_dir就够了”。但如果你的需求更细比如希望每个项目单独一个目录、打开不同项目时自动切换路径那推荐的做法不是改配置文件而是分别用启动参数启动多个Jupyter实例jupyter notebook --ServerApp.root_dirD:/ProjectA jupyter notebook --ServerApp.root_dirD:/ProjectB --port8890这样可以同时开多个实例每个实例对应不同的项目目录互不干扰。端口参数记得改一下否则第二个实例起不来。用这种方式的好处是配置文件不用来回改了适合多项目并行的用户。3.3 启动参数与快捷方式层面的路径控制如果你不想改动任何配置文件也可以在启动时临时指定路径。命令行进入目标目录后执行jupyter notebook注意这种方式下Jupyter默认把当前目录作为root_dir。比如你在D:\ProjectA目录打开终端再启动文件列表就停在D:\ProjectA。这就是很多人“没改配置但每次路径都对”的原因——不是配置生效是启动目录决定的。Windows用户如果习惯双击快捷方式启动可以通过修改快捷方式属性来控制起始位置。右键Jupyter Notebook快捷方式 - 属性 - 快捷方式选项卡把起始位置改成你想要的目录再点确定。这样每次双击启动Jupyter就会自动用这个目录作为工作目录效果和命令行cd进去再启动是一样的。另外推荐一个更灵活的方式自己写一个批次处理脚本内容大概这样echo off cd /d D:\JupyterProjects python -m jupyter notebook --ServerApp.root_dirD:\JupyterProjects以后启动直接双击这个批处理文件就行路径永远不会乱。注意python -m这种启动方式能确保Jupyter使用当前Python环境下的版本比直接敲jupyter命令更保险。3.4 路径配置后如何验证配置文件改完、重启之后别急着写代码先做两个验证。第一个验证看页面路径。浏览器打开Jupyter页面正常情况下地址栏应该能看到/tree结尾的URL页面左侧文件树应该显示你配置的目录下的文件。如果你看到的还是老路径说明配置没生效回到3.1去看配置文件有没有改对地方。第二个验证在页面里新建一个Notebook输入一段简单代码比如import os; print(os.getcwd())然后运行看当前工作目录是不是你设置的那个。这个验证最直接因为它能测出内核实际的工作路径跟文件树路径是不是一致的。有时候文件树路径对了但内核工作目录还是旧目录这种就需要额外设置不过对于大多数场景root_dir改好之后两者是一致的。4. 新版常见问题的排查与急救4.1 安装后打不开、白屏或一直转圈这是v7用户最常遇到的第一道坎一般分三种情况。第一种是安装完成后在终端敲jupyter notebook提示找不到命令或模块。这种情况多半是环境变量没配置好或者你装了多个Python环境命令入口指向了错误位置。直接改用python -m jupyter notebook启动不要用裸命令。第二种是浏览器打开后页面白屏或者一直转圈。通常原因是Jupyter Server没有正常启动端口被占用或者页面加载了损坏的静态资源。先看终端有没有报错有报错就按报错处理没报错就尝试强制刷新浏览器缓存或者用CtrlShiftR清掉Service Worker缓存。如果依然白屏停掉Jupyter进程执行pip install --force-reinstall jupyterlab notebook重新装一次前端资源。第三种是端口被占提示Port 8888 is already in use。输入jupyter notebook --port8889换一个端口启动或者找到占用进程结束掉再试。用netstat -ano | findstr :8888Windows或者lsof -i:8888macOS/Linux查看占用情况即可。4.2 单元格执行没有任何反应页面能打开文件能新建但点运行单元格一点反应都没有控制台也没有输出。这个问题和内核有关跟页面本身无关。先检查内核状态jupyter kernelspec list确认当前Python版本对应的内核存在。如果列表是空的说明缺少ipykernel执行pip install ipykernel python -m ipykernel install --user装完后重启Notebook再试。如果你用了conda环境记得先激活目标环境再执行上面的命令否则内核会装到别的Python里去。激活后可以用python -m ipykernel install --user --name 环境名 --display-name 显示名指定环境安装内核。另外检查一下是不是所有单元格都没反应还是只有某一行代码没反应。如果所有单元格都没反应大概是jupyter_client和pyzmq版本冲突了执行pip install -U jupyter_client pyzmq再重启服务。4.3 导入包时DLL Load Failed错误这个错误在Windows上很常见报错信息类似ImportError: DLL load failed while importing rpds。rpds是rpds-py这个库里的一个模块新版Jupyter依赖链里引到了它但这个库在某些Python版本下的预编译二进制有问题导入时就崩了。解决办法按顺序试pip uninstall rpds-py -y pip install rpds-py --force-reinstall如果还不行升级pip和构建工具python -m pip install --upgrade pip setuptools wheel pip install rpds-py --force-reinstall实在不行的去PyPI上下载对应Python版本、对应系统架构的rpds-py的wheel包手动安装。注意台式机和笔记本的系统架构一般是amd64但有些ARM架构设备需要下载arm64版本别下错了。这个问题在Python 3.12和3.13上出现频率更高如果处理不了又不想折腾最简单的方案是把Python环境降到3.10这一版本下整个Jupyter生态最稳定。4.4 汉化失效或语言包不回显装了语言包、界面也选了中文重启后又变回英文。这种情况很多人遇到过通常有三个原因。第一个原因是语言包和Jupyter版本不匹配。Jupyter Notebook v7.0.x和v7.1.x对应的JupyterLab语言包版本可能不同升级Notebook之后语言包没跟着升级就会出现加载不上的情况。统一执行pip install -U jupyterlab-language-pack-zh-CN即可。第二个原因是浏览器缓存。Jupyter前端资源大量使用了缓存机制语言切换后的新资源可能没被浏览器重新加载。进入开发者工具彻底清空站点数据再刷新页面问题一般能解决。第三个原因最隐蔽同时装了旧版jupyterlab-language-pack的遗留文件导致语言包解析失败。这种情况卸载干净再重装pip uninstall jupyterlab-language-pack-zh-CN -y pip install jupyterlab-language-pack-zh-CN如果不想重装这么麻烦也可以直接删掉C:\Users\你的用户名\.jupyter\lab目录下的缓存文件后重启服务这个操作安全Jupyter会自动重建。5. 周边环境联动编辑器里的Jupyter与汉化通用思路5.1 VS Code、Cursor里的Jupyter前缀与路径现在不少人不用网页版直接在VS Code或者Cursor这样的编辑器里写Notebook。代码块前面的In/Out标签和单元格交互是编辑器的功能走的不是JupyterServer的页面逻辑。所以你在编辑器里看到的界面是否中文取决于编辑器自身的中文语言包跟Jupyter那边没多大关系。以VS Code为例装一个Chinese (Simplified) Language Pack扩展就能够让编辑器界面变中文。编辑器里跑Jupyter内核时文件保存路径默认跟随工作区目录。如果你希望所有Notebook统一保存到某个目录修改VS Code设置搜索notebookFileRoot把它改成$workspaceFolder或指定绝对路径。Cursor的情况跟VS Code基本一致因为它是VS Code的改版。如果你已经给VS Code装过中文扩展到了Cursor里还需要重新装一次两个软件的数据不完全互通。这种方式的好处是不用折腾浏览器页面的汉化工作区管理和路径控制都交给了编辑器本身。坏处是你如果还在浏览器里单独使用Jupyter两端配置不互通要维护两份设置。5.2 Web界面汉化的通用思路做多了会发现Jupyter Notebook v7的汉化思路和很多Web应用的汉化套路其实是一样的应用本体不内置多语言而是通过语言包插件动态加载翻译资源。你平时可能接触过的Postman、设计工具、终端模拟器都是这个套路。安装语言包、在设置里切换语言、刷新页面三步走。理解了这个通用思路遇到其他类似的Web应用汉化时就不会手足无措。关键点是找到对应的语言包源。PyPI上有专门的项目维护Jupyter语言包所以一条pip命令就能解决。有些软件语言包在应用商店里直接搜有些需要去GitHub项目Release页面下载本质流程没区别。这个思路对GitHub汉化这类需求也适用GitHub本身是网页应用它的汉化往往借助浏览器插件或者油猴脚本因为网页应用不像本地应用那样能方便地装全局语言包。下载下来后同样是注册、刷新两步操作。如果你想手动添加翻译包印象中有个思路是直接在Jupyter的settings目录下写一个overrides.json文件强制覆盖语言选项。这种方式相当于绕过界面配置、直接改内部设置属于进阶玩法如果你对Jupyter配置结构足够熟悉可以试一下。对多数人来说用pip安装官方语言包已经够用了。5.3 多环境配置的避坑建议最后聊一个很多人都会踩的坑conda创建了多个环境每个环境里都装了Jupyter导致汉化、路径配置来来回回不对。最稳妥的方法其实很笨确定你最常用的那个环境把它设成默认环境所有Jupyter相关操作都从它发起另一个环境用的时候才激活。这样你只需要维护一套Jupyter配置。如果你确实需要多个环境都具备完整的Jupyter能力那就老老实实每个环境都装一遍conda activate env_name pip install jupyter notebook jupyterlab-language-pack-zh-CN ipykernel jupyter notebook --generate-config然后分别配置各自的配置文件。这个过程确实繁琐但能避免后续大把的“为什么这个环境里没有”的疑问。还有一个小技巧在配置文件的头部加一行import os os.environ[PYTHONPATH] D:/JupyterProjects这样即使切了环境Python模块搜索路径也保持一致减少因为当前目录不同导致导入失败的烦躁时刻。这个方法不是官方推荐的PYTHONPATH设置不当容易造成模块版本混乱但如果你只是在一台自己用的机器上写代码实测下来还挺省心的。根据我个人的实际体验新版Jupyter Notebook最麻烦的不是配置有多难而是很多人不知道它已经悄悄换了一套底层机制还在拿旧教程硬套。搞清楚架构变化之后汉化和路径配置其实都是几分钟的事。如果你在操作过程中遇到了上面没写到的怪问题建议先去终端启动Jupyter看日志输出90%的问题答案都藏在红色的报错信息里。
