{"id":9972,"library":"nbdev","title":"nbdev: Notebook Driven Development","description":"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.","status":"active","version":"3.0.15","language":"en","source_language":"en","source_url":"https://github.com/AnswerDotAI/nbdev","tags":["jupyter","notebooks","development","documentation","testing","cli","literate-programming"],"install":[{"cmd":"pip install nbdev","lang":"bash","label":"Install nbdev"}],"dependencies":[{"reason":"Provides core utilities and data structures leveraged by nbdev.","package":"fastcore"}],"imports":[{"note":"Commonly imported within notebooks to display docstrings for exported functions/classes.","symbol":"show_doc","correct":"from nbdev.showdoc import show_doc"}],"quickstart":{"code":"# 1. Create a new nbdev project (run in your terminal)\nnbdev_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\ncd my_nbdev_project\n\n# 2. Open 00_core.ipynb (or create a new notebook like `01_utils.ipynb`)\n# Add a cell with `#|export` at the top and define a function:\n# #|export\n# def greet(name):\n#     \"Returns a personalized greeting\"\n#     return f\"Hello, {name}!\"\n\n# 3. Export your notebooks to Python modules\nnbdev_export\n\n# 4. Test your library\nnbdev_test\n\n# 5. Generate documentation (requires Quarto CLI installed separately)\n# nbdev_docs serve # To build and serve docs locally","lang":"bash","description":"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`."},"warnings":[{"fix":"Review the official nbdev v3 migration guide. Update CLI commands (e.g., `nbdev_build_lib` -> `nbdev_export`), refactor configuration, and adjust project structure.","message":"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.","severity":"breaking","affected_versions":"2.x to 3.x"},{"fix":"Update notebook frontmatter to the new Quarto-compatible format. Consult the nbdev documentation for the correct syntax.","message":"The notebook frontmatter syntax changed in nbdev v3 to align with Quarto's standards. Old YAML-like frontmatter may no longer be parsed correctly.","severity":"breaking","affected_versions":"2.x to 3.x"},{"fix":"Always run `nbdev_install_hooks` in the root of your nbdev project. This sets up git hooks to automatically clean notebooks on commit.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Download and install the Quarto CLI from the official Quarto website (quarto.org) for your operating system.","message":"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.","severity":"gotcha","affected_versions":"All versions (where docs are generated)"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","cause":"The nbdev package is not installed or its CLI tools are not in your system's PATH.","error":"nbdev_export: command not found"},{"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`.","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.","error":"ModuleNotFoundError: No module named 'your_project_name.core'"},{"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.","cause":"The `nbdev_docs` command relies on the external Quarto command-line interface, which is not found on your system.","error":"ERROR: QUARTO NOT INSTALLED. Please install quarto from quarto.org."},{"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.","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.","error":"Git command `git diff --name-only --cached --diff-filter=ACM` failed with exit code 128"}]}