nbdev — Write, Test, and Document Python Libraries in Jupyter Notebooks

Introduction

nbdev turns Jupyter notebooks into a complete development environment. You write code, tests, and documentation in the same notebook, and nbdev exports clean Python modules, runs tests from notebook cells, and generates a Quarto-based documentation site. It was created by fast.ai to develop their deep learning library.

What nbdev Does

• Exports notebook cells marked with #| export into standard Python .py modules
• Runs every code cell as a test, catching regressions without a separate test file
• Generates a documentation site with live examples from notebook outputs
• Manages git-friendly notebook diffs with clean cell metadata
• Handles package publishing to PyPI with nbdev_pypi and conda with nbdev_conda

Architecture Overview

nbdev uses directive comments (#| export, #| hide, #| test) to control what happens with each cell. The nbdev_export command parses notebooks, extracts cells tagged for export, and writes them into a Python package structure. Tests are the notebook cells themselves—nbdev_test executes all notebooks in parallel, treating any cell error as a test failure. Documentation is generated via Quarto, rendering notebooks into a static site with executed outputs.

Installation & Configuration

• Install via pip: pip install nbdev
• Run nbdev_new to scaffold a project with settings.ini configuration
• Configure library name, version, author, and module structure in settings.ini
• Set up GitHub Actions CI with nbdev_test for automated testing on every push
• Use nbdev_install_hooks for git pre-commit hooks that clean notebook metadata

Key Features

• Single-source development: code, tests, and docs live in the same notebook
• Parallel notebook testing executes hundreds of cells in seconds
• Two-way sync between notebooks and Python source files via nbdev_export and nbdev_update
• Quarto integration produces documentation sites with searchable API references
• GitHub Actions templates for CI/CD, PyPI publishing, and documentation deployment

Comparison with Similar Tools

• Jupyter + pytest — separate test files and manual export; nbdev unifies everything in notebooks
• Sphinx — documentation from docstrings; nbdev generates docs from rich notebook content with outputs
• Quarto alone — rendering notebooks as documents; nbdev adds module export, testing, and packaging
• Papermill — parameterized notebook execution; nbdev focuses on library development, not data pipelines
• Jupytext — syncs notebooks with scripts; nbdev adds testing, docs, and package management on top

FAQ

Q: Can I use nbdev for non-ML projects? A: Yes. nbdev works for any Python library. The fast.ai team uses it for utility libraries, web frameworks, and CLI tools.

Q: How does testing work without pytest? A: Every code cell in a notebook is a test. nbdev_test runs all notebooks; any cell that raises an exception fails the test suite.

Q: Does nbdev support standard Python package structure? A: Yes. Exported modules follow standard package conventions and install via pip like any other Python library.

Q: Can I still edit the generated .py files directly? A: You can, but nbdev_update syncs changes back to notebooks. The recommended workflow is notebook-first.

Sources

• https://github.com/fastai/nbdev
• https://nbdev.fast.ai/