From Notebook to Library: How nbdev Rethinks Python Development

Software engineering best practices—unit testing, documentation, and continuous integration—are often treated as afterthoughts or, worse, barriers to entry for newcomers. The fastai team’s nbdev, which GitHub has helped support, takes a different approach: embed these practices directly into the development workflow using Jupyter notebooks as the single source of truth.

Nbdev is built on the idea of literate programming, a concept popularized by Donald Knuth that describes a move away from writing programs “in the manner and order imposed by the computer,” and instead letting developers structure code around the “logic and flow of their thoughts.” While fragments of this idea appear in tools like Jupyter, Mathematica, and Swift Playgrounds, nbdev aims to cover the entire software life cycle, not just the exploratory phase.

Integrated Tooling for an Entire Project

Nbdev leverages Jupyter notebooks as the primary authoring environment and extends them with features that address the full range of project needs:

  • Documentation generation: Notebooks are automatically converted into searchable documentation sites hosted on GitHub Pages. The docs are “intelligently hyperlinked” so that when you reference a term in backticks, nbdev introspects that keyword and links it to the appropriate documentation page.
  • Built-in CI: GitHub Actions workflows are set up for you by default, and tests run automatically in parallel via a single CLI command. No prior knowledge of Actions is required.
  • Two-way sync: Nbdev synchronizes between notebooks and generated source code. You can use your IDE for navigation or quick edits without breaking the notebook workflow.
  • Testing in context: Unit tests are written directly in notebooks—no special API to learn. These tests are executed by the CLI and by GitHub Actions.
  • Readable merge tools: Utilities are included to handle notebook merge/conflict resolution in a human-readable format.
  • Packaging utilities: Nbdev helps automate publishing to PyPI and conda.

The environment itself is designed for smooth onboarding in GitHub Codespaces, bringing together the notebook editor, a local docs preview server, and CLI tools in a single workspace.

Removing Friction From the Development Lifecycle

The core thesis behind nbdev is that when documentation and testing live in the same place as the source code itself, developers are more likely to write them—and to write them well. By removing the need to learn web development or CI configuration, nbdev lowers the cognitive load for contributing high-quality software and makes good engineering practices more accessible to a wider audience.

This approach is not limited to building Python libraries. Nbdev has been used as a foundation for extending its own capabilities, such as in fastpages, a blogging platform that converts notebooks into posts, and in covid19-dashboards, which shows how to build interactive, automatically updating dashboards from Jupyter notebooks. Both projects use GitHub Actions and GitHub Pages extensively.

The nbdev project is an open-source effort, and its maintainers are hoping it inspires the next generation of literate programming environments. For those interested in exploring further, the official nbdev documentation covers feature details, and a full walkthrough is available through a minimal end-to-end effect. The project’s background is captured on the fast.ai blog and in a talk from JupyterCon. Community discussion takes place on the fast.ai forums and GitHub.