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

> nbdev is a literate programming framework by fast.ai that lets you develop complete Python packages inside Jupyter notebooks, with automatic module export, continuous integration testing, and documentation generation.

## Install

Save in your project root:

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

## Quick Use
```bash
pip install nbdev
nbdev_new          # scaffold a new project
```
```python
# In a notebook cell:
#| export
def say_hello(name):
    """Say hello to someone."""
    return f"Hello, {name}!"
```
```bash
nbdev_export       # export to .py modules
nbdev_test         # run all notebook tests
nbdev_docs         # build documentation
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-48637563
Author: AI Open Source