nbdev：用 Jupyter Notebook 搞定完整的 Python 项目开发

fastai 团队出品的 nbdev 在 GitHub 上积累了 5299 颗星。这个工具的核心理念很简单：你只管在 Jupyter Notebook 里写代码和注释，文档、测试、打包、CI 这些杂事它全自动搞定。

对习惯用 Notebook 做数据分析或原型开发的人来说，这相当于把「玩具代码」升级成「工程级项目」的桥梁。

它到底能做什么

nbdev 的功能覆盖了一个 Python 项目从开发到发布的完整链路：

文档自动生成。基于 Quarto 把 Notebook 渲染成静态网站，支持 LaTeX、搜索、自动超链接，直接托管到 GitHub Pages。你写在 Notebook 里的 Markdown 注释就是文档源码，不需要再维护一套独立的文档系统。

双向代码同步。Notebook 里的导出单元格可以生成标准的 .py 模块文件，反过来也能把模块的改动同步回 Notebook。每个单元格都带了唯一 ID，不会出现改错位置的情况。

测试内嵌执行。Notebook 里的普通代码单元格可以直接当测试用，nbdev-test 命令会并行跑完。测试和开发写在同一个文件里，不用在测试目录和源码目录之间来回切。

一键发布。内置 PyPI 和 conda 的发布命令，自动处理版本号、CHANGELOG、all 导出列表这些细节。

Git 友好。自带 Jupyter/Git hooks，提交时自动清理 Notebook 元数据，遇到合并冲突还能渲染成可读格式解决。

2026 年的重大更新

今年 1 月发布的 nbdev3 做了一次不兼容升级：项目配置从 settings.ini 迁移到了 pyproject.toml，符合 PEP 621 标准。项目元数据放在 [project] 区块，nbdev 专属配置放在 [tool.nbdev] 区块。老项目可以跑 nbdev-migrate-config 自动迁移，Notebook 和代码本身不需要改动。

这个改动方向是对的。pyproject.toml 已经是现代 Python 项目的标配，nbdev 不再搞自己的配置格式，接入生态更方便了。

谁适合用

如果你符合以下任意场景，nbdev 值得尝试：

• 经常用 Notebook 写 Python，但受够了手动复制代码到 .py 文件
• 想做开源项目，不想维护文档站、测试框架、发布流程一堆工具链
• 团队内部有大量 Notebook 形式的知识沉淀，想规范成可发布的库

fastai 自己的深度学习库、ghapi、fastcore 这些项目都是用 nbdev 开发的，工程强度经得起验证。

一点提醒

nbdev 目前不支持 Windows 原生的 cmd 或 Powershell，需要在 WSL 或类 Unix 环境下运行。如果你是 Windows 用户，先确认自己的开发环境能兼容。

另外，Notebook 里别把 import 语句和其他代码混在同一个单元格，nbdev 生成文档时会单独执行 import 单元格来提取函数签名，混在一起的代码会被误执行。

总的来说，nbdev 解决的是一个很具体的痛点：让 Notebook 既能保持探索性开发的灵活性，又能输出符合工程规范的项目产物。它的目标人群是已经习惯 Notebook 的人，帮他们打通从原型到发布的路径，而非要求所有人迁移到 Notebook 开发。

ebook 的人，帮他们打通从原型到发布的路径，而非要求所有人迁移到 Notebook 开发。