nbdev: Notebook Driven Development

3.0.15 · active · verified Fri Apr 17

nbdev is a Python library that enables a complete literate programming environment, allowing users to develop, test, document, and deploy software using Jupyter Notebooks. It leverages Quarto for powerful documentation generation and provides a robust command-line interface for managing the development workflow. Currently at version 3.0.15, nbdev maintains a rapid release cadence, frequently pushing minor updates and bug fixes.

Common errors

```
nbdev_export: command not found
```
cause The nbdev package is not installed or its CLI tools are not in your system's PATH.

fix Ensure nbdev is installed using `pip install nbdev`. If using a virtual environment, activate it before running commands. You may need to restart your terminal.
```
ModuleNotFoundError: No module named 'your_project_name.core'
```
cause This error typically occurs when trying to import a module that hasn't been created yet or isn't in Python's import path. Often, `nbdev_export` hasn't been run, or there's an issue with the project setup.

fix Run `nbdev_export` from your project's root directory. Ensure your notebook contains cells marked `#|export` and that your `pyproject.toml` (or `settings.py`) correctly defines `lib_name`.
```
ERROR: QUARTO NOT INSTALLED. Please install quarto from quarto.org.
```
cause The `nbdev_docs` command relies on the external Quarto command-line interface, which is not found on your system.

fix Download and install the Quarto CLI from https://quarto.org/docs/get-started/ for your operating system. Ensure it's added to your system's PATH.
```
Git command `git diff --name-only --cached --diff-filter=ACM` failed with exit code 128
```
cause This often indicates issues with the git hooks managed by nbdev, possibly due to a `.git` directory problem or incorrect hook setup, especially after cloning or moving a repository.

fix Navigate to your project root and run `nbdev_install_hooks`. If the problem persists, manually check your `.git/hooks` directory or re-initialize git if safe to do so.

Warnings

breaking nbdev v3 introduced significant breaking changes, including a complete rewrite of CLI commands, migration from `settings.ini` to `pyproject.toml` for configuration, and a new directory structure.
Fix: Review the official nbdev v3 migration guide. Update CLI commands (e.g., `nbdev_build_lib` -> `nbdev_export`), refactor configuration, and adjust project structure.
breaking The notebook frontmatter syntax changed in nbdev v3 to align with Quarto's standards. Old YAML-like frontmatter may no longer be parsed correctly.
Fix: Update notebook frontmatter to the new Quarto-compatible format. Consult the nbdev documentation for the correct syntax.
gotcha Not running `nbdev_install_hooks` after creating or cloning a project can lead to notebooks with dirty outputs being committed to Git, which can cause merge conflicts or unnecessary diffs.
Fix: Always run `nbdev_install_hooks` in the root of your nbdev project. This sets up git hooks to automatically clean notebooks on commit.
gotcha The `nbdev_docs` command requires the Quarto CLI tool to be installed and available in your system's PATH. nbdev does not install Quarto for you.
Fix: Download and install the Quarto CLI from the official Quarto website (quarto.org) for your operating system.

Install

pip install nbdev Install nbdev

Imports

show_doc
```
from nbdev.showdoc import show_doc
```
Commonly imported within notebooks to display docstrings for exported functions/classes.

Quickstart

This quickstart demonstrates the typical nbdev CLI workflow: creating a new project, exporting notebook code to Python modules, running tests, and generating documentation. Remember to manually create/edit a notebook file with '#|export' cells before running `nbdev_export`.

# 1. Create a new nbdev project (run in your terminal)
nbdev_new --user "Your Name" --email "your@example.com" --repo-path my_nbdev_project --git-url "https://github.com/your-username/my_nbdev_project" --lib-name my_nbdev_project
cd my_nbdev_project

# 2. Open 00_core.ipynb (or create a new notebook like `01_utils.ipynb`)
# Add a cell with `#|export` at the top and define a function:
# #|export
# def greet(name):
#     "Returns a personalized greeting"
#     return f"Hello, {name}!"

# 3. Export your notebooks to Python modules
nbdev_export

# 4. Test your library
nbdev_test

# 5. Generate documentation (requires Quarto CLI installed separately)
# nbdev_docs serve # To build and serve docs locally

view raw JSON →