1. 为什么你的 Jupyter Notebook 总是“差点意思”很多人第一次装完 Jupyter Notebook打开浏览器看到那个文件列表页面觉得“能用就行”。但用了一段时间之后问题就开始冒出来了默认目录里堆满了乱七八糟的.ipynb文件想换个盘符存项目得先cd半天装了几十个库之后不同项目之间的依赖开始打架A 项目要numpy 1.21B 项目要numpy 1.26一升级就崩每次打开 Notebook 都要手动敲一遍import pandas as pd和那几行 matplotlib 中文字体设置烦得要命。这些问题的根源其实都一样你用的是“默认配置”的 Jupyter Notebook而不是“你自己的” Jupyter Notebook。默认配置是给“第一次打开就能看到界面”这个最低目标设计的它不考虑你后续几百个小时的使用体验。而配置的本质就是把你反复要做的事情变成一次性的设置把你容易搞混的东西隔离开把你每次都要敲的代码变成自动执行的模板。这篇文章面向的是已经装好 Jupyter Notebook、能跑起来基本代码、但还没认真折腾过配置的人。我会从工作目录、虚拟环境内核、界面主题、快捷键、自动加载扩展、默认导入模板这几个最影响日常体验的维度把配置逻辑和实操步骤完整拆一遍。每个配置项我都会说清楚“为什么这么设”以及“不这么设会怎样”你照着做一遍之后每天用 Notebook 的效率至少翻一倍。2. 工作目录与启动路径别再把文件堆在默认文件夹里2.1 默认目录为什么是个坑Jupyter Notebook 安装完之后默认的启动目录通常是当前用户的主目录Windows 上是C:\Users\你的用户名macOS 和 Linux 上是/home/你的用户名或/Users/你的用户名。这意味着你每次打开 Notebook看到的文件列表是你整个主目录的内容——桌面、下载、文档、图片全混在一起。更麻烦的是当你新建一个 Notebook 时它默认保存在这个目录下。用不了多久你的主目录里就会散落着Untitled.ipynb、Untitled1.ipynb、Untitled2.ipynb这样的文件找都找不到。我见过不少人的做法是每次打开 Notebook 之后先在第一个单元格里敲import os; os.chdir(D:/projects/xxx)。这个做法能用但有两个问题第一每次都要敲忘了就存错地方第二os.chdir只改变了 Python 进程的工作目录Notebook 文件本身的保存路径还是默认目录你新建的 Notebook 还是会在主目录里。正确的做法是从启动配置层面就把工作目录固定下来。2.2 通过配置文件修改默认目录Jupyter Notebook 的配置文件是一个 Python 脚本叫jupyter_notebook_config.py。如果你还没生成过这个文件先在终端里执行jupyter notebook --generate-config这个命令会在你的用户目录下生成~/.jupyter/jupyter_notebook_config.pyWindows 上是C:\Users\你的用户名\.jupyter\jupyter_notebook_config.py。如果文件已经存在它会问你是否覆盖选N就行。用任意文本编辑器打开这个文件找到c.NotebookApp.notebook_dir这一行注意前面有个#注释符号把它改成c.NotebookApp.notebook_dir D:/workspace/notebooks路径用你实际想用的目录Windows 上注意用正斜杠/或者双反斜杠\\单反斜杠\在 Python 字符串里是转义字符会出问题。改完之后保存重新启动 Jupyter Notebook浏览器打开的就是你指定的目录了。注意如果你用的是 Anaconda 发行的 Jupyter NotebookWindows 开始菜单里的快捷方式可能覆盖了这个配置。你需要右键快捷方式 → 属性 → 把“目标”字段末尾的%USERPROFILE%删掉否则它还是会以主目录启动。2.3 更灵活的方式用快捷脚本指定不同目录固定一个工作目录适合大多数人但如果你同时维护好几个项目每个项目想用不同的目录每次改配置文件就太麻烦了。我的做法是写几个启动脚本每个脚本指定不同的目录。Windows 上建一个start_nlp.batecho off cd /d D:\workspace\nlp-project jupyter notebookmacOS 或 Linux 上建一个start_nlp.sh#!/bin/bash cd /d/workspace/nlp-project jupyter notebook给.sh文件加上执行权限chmod x start_nlp.sh之后双击或从终端运行就行。这样你每个项目一个脚本互不干扰也不用反复改配置文件。2.4 启动参数临时覆盖如果你只是偶尔需要换个目录不想改配置文件也不想写脚本可以在启动命令后面直接加参数jupyter notebook --notebook-dirE:/temp-analysis这个参数只在当次启动生效关掉就恢复默认。适合临时处理一些零散任务。3. 虚拟环境与内核配置让每个项目用自己的一套库3.1 为什么需要虚拟环境Python 的包管理有一个长期存在的问题所有包默认装在同一个全局环境里。你pip install numpy装的是全局的 numpy所有项目共用。这听起来方便实际上是个定时炸弹。假设你半年前做了一个数据分析项目用的是pandas 1.3代码跑得好好的。最近你开了个新项目需要pandas 2.0的新特性于是pip install --upgrade pandas。升级完之后新项目没问题了但半年前那个项目的代码在pandas 2.0下可能报一堆FutureWarning甚至直接报错——因为pandas 2.0移除了一些旧 API。虚拟环境就是解决这个问题的每个项目一个独立的环境各装各的包互不影响。3.2 创建虚拟环境并在 Jupyter 中注册内核假设你用venvPython 自带的虚拟环境工具完整流程是这样的# 1. 在项目目录下创建虚拟环境 cd D:/workspace/nlp-project python -m venv venv # 2. 激活虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate # 3. 安装 ipykernel这是 Jupyter 识别内核的关键包 pip install ipykernel # 4. 把虚拟环境注册为 Jupyter 内核 python -m ipykernel install --user --namenlp-project --display-namePython (NLP项目)第 4 步的--name是内核的内部标识符用英文、不带空格--display-name是在 Jupyter 界面上显示的名字可以写中文方便识别。注册完之后重启 Jupyter Notebook新建 Notebook 时就能在 Kernel 菜单里看到 “Python (NLP项目)” 这个选项了。选中它这个 Notebook 就会用你虚拟环境里的 Python 和所有包。如果你用的是conda而不是venv流程更简单conda create -n nlp-project python3.11 conda activate nlp-project pip install ipykernel python -m ipykernel install --user --namenlp-project --display-namePython (NLP项目)3.3 查看和清理已注册的内核用了一段时间之后你可能会注册一堆内核有些项目已经删了但内核还留在列表里。查看当前所有已注册的内核jupyter kernelspec list输出会列出每个内核的名称和对应的配置文件路径。要删除某个不再需要的内核jupyter kernelspec remove nlp-project这个命令只删除 Jupyter 的内核注册信息不会删除你的虚拟环境本身。虚拟环境该删的话手动把venv文件夹删掉就行。3.4 一个容易踩的坑内核注册了但包找不到有时候你明明在虚拟环境里pip install了某个包但在 Jupyter 里import却报ModuleNotFoundError。这通常是因为你注册内核时用的python -m ipykernel里的python不是虚拟环境里的那个。验证方法很简单在 Notebook 里运行import sys print(sys.executable)输出的路径应该指向你的虚拟环境目录比如D:/workspace/nlp-project/venv/Scripts/python.exe。如果指向的是全局 Python 路径说明内核注册错了需要先激活虚拟环境再重新注册。4. 界面、主题与快捷键把 Notebook 调成顺手的样子4.1 安装并启用主题Jupyter Notebook 默认的白色界面看久了眼睛累尤其是晚上写代码的时候。社区有一个叫jupyterthemes的包可以换各种配色方案。pip install jupyterthemes安装完之后先看看有哪些可用主题jt -l会列出chesterish、grade3、gruvboxd、gruvboxl、monokai、ocean16、onedork、solarizedd、solarizedl这些主题。我个人常用onedork深色背景、语法高亮对比度适中长时间看不容易疲劳。应用主题的命令jt -t onedork -fs 13 -cellw 90% -lineh 150 -T -N参数说明-t onedork指定主题名称-fs 13代码字体大小 13pt-cellw 90%单元格宽度占页面 90%-lineh 150行高 150%-T显示工具栏-N显示 Notebook 名称这几个参数是我试了多次之后觉得比较舒服的组合。你可以根据自己的屏幕尺寸和视力情况调整-fs和-cellw。想恢复默认主题的话jt -r注意jupyterthemes有时会和 Jupyter Notebook 的版本更新冲突导致界面元素错位。如果遇到这种情况先jt -r恢复默认等主题包更新之后再试。4.2 自定义快捷键Jupyter Notebook 的快捷键分两种模式编辑模式光标在单元格里边框是绿色和命令模式光标不在单元格里边框是蓝色。按Esc进入命令模式按Enter进入编辑模式。默认快捷键里我觉得最有用的是这几个快捷键模式功能Shift Enter两种运行当前单元格并跳到下一个Ctrl Enter两种运行当前单元格并留在原地Alt Enter两种运行当前单元格并在下方插入新单元格A命令在上方插入新单元格B命令在下方插入新单元格DD命令删除当前单元格M命令把当前单元格转为 MarkdownY命令把当前单元格转为代码Shift M命令合并选中的多个单元格这些默认快捷键已经覆盖了大部分日常操作。如果你有特殊需求比如经常要折叠代码块可以自己加。自定义快捷键需要修改~/.jupyter/custom/custom.js文件。如果custom目录不存在手动建一个。在里面写入// 添加快捷键CtrlShiftF 折叠当前代码单元格 Jupyter.keyboard_manager.command_shortcuts.add_shortcut(ctrl-shift-f, { help: 折叠/展开当前单元格, help_index: zz, handler: function (event) { Jupyter.notebook.get_selected_cell().toggle_line_numbers(); return false; } });这个例子的实际功能是切换行号显示你可以把handler里的逻辑换成任何你想要的操作。改完之后刷新浏览器页面生效。4.3 关闭自动补全的干扰Jupyter Notebook 自带的自动补全是用Tab键触发的但有时候你按Tab是想缩进它却弹出一个补全列表很烦。如果你更习惯手动触发补全可以在设置里关掉自动弹出。在 Notebook 界面菜单栏点Help→Edit Keyboard Shortcuts找到autocomplete相关的条目把触发键改成你习惯的组合。或者直接在custom.js里禁用Jupyter.keyboard_manager.edit_shortcuts.remove_shortcut(tab);这样Tab就只做缩进补全用Ctrl Space手动触发。5. 扩展插件让 Notebook 长出你需要的那双手5.1 安装 nbextensionsJupyter Notebook 本身的功能比较基础但社区开发了大量扩展插件可以加上目录、代码折叠、变量检查器、执行时间显示等功能。管理这些插件的工具叫nbextensions。安装步骤pip install jupyter_contrib_nbextensions jupyter contrib nbextension install --user pip install jupyter_nbextensions_configurator jupyter nbextensions_configurator enable --user装完之后重启 Jupyter Notebook在文件列表页面会多出一个Nbextensions标签页里面列出了所有可用插件勾选就能启用。5.2 我必开的五个插件插件列表很长但真正高频使用的就那么几个。以下是我每台机器上都会开的Table of Contents (2)在左侧生成一个目录树根据 Markdown 标题自动生成。长 Notebook 没有这个根本没法导航。建议勾选Add a collapsible section和Automatically update the TOC。Codefolding代码折叠。写长函数的时候可以把不关心的部分折起来界面清爽很多。在设置里把Codefolding in Editor和Codefolding in Code Cells都勾上。Variable Inspector变量检查器。在右上角弹出一个面板实时显示当前内存里所有变量的名称、类型、大小和值。调试的时候不用反复print了直接看面板就行。注意这个插件对大数据量的变量会有性能影响如果内存里有个几百万行的 DataFrame面板刷新会卡可以临时关掉。ExecuteTime在每个单元格下方显示执行时间和完成时间。优化代码的时候特别有用你能直观看到哪个单元格是性能瓶颈。Hinterland增强版自动补全。Jupyter 自带的补全只匹配当前命名空间里已有的变量和函数Hinterland 会在你打字的时候实时弹出补全建议类似 IDE 的体验。勾选Hinterland之后在设置里把hint_delay调到 300 毫秒左右太快了会频繁弹窗干扰太慢了又没意义。5.3 插件冲突与性能问题插件装多了之后Notebook 的加载速度会变慢偶尔还会出现界面元素错位。我遇到过两种情况一种是Table of Contents和Codefolding同时开启时目录树的折叠箭头和代码折叠的箭头位置重叠点错是常事。解决办法是把Table of Contents的面板宽度调大一点在插件设置里改toc_window_display和toc_sidebar_width。另一种是Variable Inspector在 Notebook 单元格很多的时候每次执行都刷新整个面板导致明显的卡顿。如果你不需要实时监控变量可以改成手动刷新模式在插件设置里取消勾选Auto-refresh。提示如果你发现 Notebook 启动明显变慢可以先在Nbextensions页面把所有插件取消勾选然后逐个开启找出是哪个插件拖慢了速度。通常Variable Inspector和Hinterland是性能影响最大的两个。6. 默认导入与启动脚本把重复代码消灭在打开之前6.1 用 startup 文件夹自动执行代码每次新建 Notebook 都要敲一遍import pandas as pd、import numpy as np、import matplotlib.pyplot as plt还要设置中文字体和负号显示这太浪费时间了。Jupyter 有一个机制可以在每个 Notebook 启动时自动执行一段代码。找到你的 IPython 配置目录通常在~/.ipython/profile_default/startup/。如果目录不存在手动创建。在里面新建一个00-startup.py文件文件名前面的数字决定执行顺序00 最先执行写入import pandas as pd import numpy as np import matplotlib.pyplot as plt import seaborn as sns # 设置 matplotlib 中文字体 plt.rcParams[font.sans-serif] [SimHei] plt.rcParams[axes.unicode_minus] False # 设置 pandas 显示选项 pd.set_option(display.max_columns, 50) pd.set_option(display.max_rows, 100) pd.set_option(display.width, 200) # 设置 seaborn 风格 sns.set_style(whitegrid) print(Startup script loaded.)保存之后重启 Jupyter Notebook新建任何 Notebook 都会自动执行这段代码。你打开就能直接用pd、np、plt不用再手动导入。6.2 按项目定制启动脚本全局的 startup 脚本适合放那些所有项目都用的东西比如 pandas、numpy、matplotlib。但如果你某个项目需要特定的初始化代码比如加载一个自定义的工具模块、设置特定的随机种子、连接数据库全局脚本就不合适了。这种情况可以用项目级的启动脚本。在项目目录下建一个.ipython/profile_default/startup/目录把项目专用的初始化代码放进去。然后启动 Notebook 时指定 IPython 配置目录jupyter notebook --IPythonApp.profile_dirD:/workspace/nlp-project/.ipython这样这个项目下的 Notebook 会先执行全局 startup再执行项目级 startup两层互不干扰。6.3 用模板文件代替 startup 脚本startup 脚本的缺点是它是“隐式”的——你打开一个 Notebook看到里面是空的但实际上已经有一堆变量和设置被加载了。如果你把 Notebook 分享给别人别人打开后可能因为缺少 startup 脚本而报错。另一种做法是用模板文件。建一个template.ipynb里面写好所有常用的导入和设置每次新建项目时复制一份改名。这样所有代码都是显式的分享出去也不会出问题。我的做法是两者结合全局 startup 只放最基础的import pandas as pd和import numpy as np这两行因为几乎所有项目都要用其他项目相关的设置放在模板文件里显式写在 Notebook 的第一个单元格。7. 配置文件版本管理与迁移7.1 哪些配置文件值得备份折腾好一套顺手的配置之后换电脑或者重装系统时不想从头再来一遍。以下这些文件值得备份文件/目录作用位置jupyter_notebook_config.py主配置工作目录、端口等~/.jupyter/custom.js自定义快捷键和界面行为~/.jupyter/custom/custom.css自定义样式~/.jupyter/custom/startup/目录自动执行脚本~/.ipython/profile_default/kernels/目录已注册的内核信息~/.local/share/jupyter/kernels/Linux或%APPDATA%\jupyter\kernelsWindows把这些文件复制到新机器上对应的位置大部分配置就能直接迁移。内核信息迁移后可能需要重新注册因为虚拟环境的路径变了。7.2 用 Git 管理配置更稳妥的做法是把这些配置文件纳入 Git 版本管理。在~/.jupyter/目录下初始化一个 Git 仓库cd ~/.jupyter git init git add jupyter_notebook_config.py custom/ git commit -m initial jupyter config然后在远程建一个私有仓库推上去。换机器的时候git clone下来把文件放到对应位置就行。注意jupyter_notebook_config.py里可能包含一些敏感信息比如如果你配置了密码或者 token不要直接推到公开仓库。可以用环境变量或者单独的 secrets 文件来管理敏感部分。7.3 迁移后的验证清单在新机器上恢复配置之后按这个清单逐项验证启动 Jupyter Notebook确认工作目录是否正确新建 Notebook确认 startup 脚本是否自动执行看有没有打印 “Startup script loaded.”检查 Kernel 菜单里是否有你注册的虚拟环境内核打开Nbextensions页面确认插件是否还在插件本身需要在新机器上重新pip install但勾选状态会保留测试自定义快捷键是否生效确认主题是否应用主题也需要重新pip install jupyterthemes如果某一步没通过回到对应的章节检查配置。8. 几个我踩过的坑和对应的解法8.1 端口被占用导致启动失败Jupyter Notebook 默认用 8888 端口。如果你同时开了多个 Notebook 实例或者 8888 端口被其他程序占了启动时会报OSError: [Errno 98] Address already in use。解决办法有两个一是关掉占用端口的程序二是换一个端口启动jupyter notebook --port8889如果你经常需要开多个实例可以在配置文件里把端口设成 0这样 Jupyter 会自动找一个空闲端口c.NotebookApp.port 0启动后终端会打印实际使用的端口号复制到浏览器就行。8.2 浏览器打开是空白页有时候 Jupyter 服务启动了终端显示正常运行但浏览器打开是空白页。这通常是浏览器缓存或者代理设置的问题。先试试强制刷新Ctrl Shift R。如果不行换一个浏览器或者用无痕模式打开。如果无痕模式能打开说明是缓存问题清一下浏览器缓存就行。还有一种情况是你之前配置过代理浏览器走了代理但 Jupyter 服务在本地不走代理导致请求发不出去。检查一下系统的代理设置把localhost和127.0.0.1加到代理排除列表里。8.3 内核频繁断开连接Notebook 用着用着突然提示 “Kernel disconnected”然后所有变量都没了。这种情况通常是因为内核进程崩溃了。常见原因有三个一是内存不够。如果你加载了一个超大的数据集把内存吃满了操作系统会杀掉内核进程。解决办法是减小数据量或者用分块读取的方式处理。二是某个库的版本冲突导致段错误。这种情况比较难排查可以看终端里有没有输出错误信息。如果有Segmentation fault字样通常是 C 扩展层面的问题尝试升级或降级相关库。三是 Notebook 本身的问题。有时候某个单元格里的死循环或者无限递归会把内核卡死。按工具栏上的中断按钮方块图标可以强制停止执行如果不行就重启内核圆圈箭头图标。8.4 保存时提示 “File changed on disk”这个提示的意思是你在 Notebook 里编辑的同时磁盘上的文件被其他程序修改了比如你同时在用另一个编辑器打开同一个文件或者有自动同步工具在跑。Jupyter 不知道该以哪个版本为准所以让你选。如果你确定 Notebook 里的版本是最新的选 “Overwrite” 覆盖磁盘文件。如果你不确定选 “Reload” 从磁盘重新加载但会丢失你在 Notebook 里未保存的修改。避免这个问题的办法是不要同时用多个工具编辑同一个.ipynb文件。如果必须这样做养成频繁Ctrl S保存的习惯。8.5 中文显示为方块matplotlib 默认字体不支持中文画图时中文会显示成方块。解决办法是在绘图之前设置中文字体plt.rcParams[font.sans-serif] [SimHei] # Windows # plt.rcParams[font.sans-serif] [Arial Unicode MS] # macOS plt.rcParams[axes.unicode_minus] FalseSimHei是 Windows 自带的黑体macOS 上可以用Arial Unicode MS或PingFang SC。Linux 上需要先确认系统里装了中文字体用fc-list :langzh查看可用字体然后把字体名称填进去。如果设置之后还是方块可能是字体名称写错了。用matplotlib.font_manager查一下系统里实际可用的字体名称from matplotlib import font_manager for font in font_manager.fontManager.ttflist: if Hei in font.name or Song in font.name: print(font.name)把打印出来的名称填到font.sans-serif列表里。9. 配置完成后的日常使用建议配置折腾完之后日常使用中还有几个小习惯能让你少踩坑。第一每个项目一个独立的虚拟环境和内核不要图省事所有项目共用一个环境。前期多花两分钟建环境后期省下的是几小时的排查时间。第二Notebook 文件不要太大。一个.ipynb文件如果超过几兆打开和保存都会变慢。如果你有一个很长的分析流程拆成多个 Notebook用模块化的方式组织比如01-data-cleaning.ipynb、02-feature-engineering.ipynb、03-modeling.ipynb。第三定期清理输出。Notebook 里的图表和打印输出会嵌入到.ipynb文件里让文件体积膨胀。在保存之前用菜单栏的Cell→All Output→Clear清掉所有输出文件会小很多。如果你用 Git 管理 Notebook清输出之后再提交diff 会干净很多。第四养成用 Markdown 单元格写注释的习惯。代码是给机器执行的注释是给人看的。三个月后你回来看自己的 Notebook如果没有 Markdown 说明你可能完全不记得当时为什么这么写。第五配置文件改完之后一定要重启 Jupyter Notebook 才生效。我见过不少人改完配置发现没变化以为配置写错了其实只是没重启。