Getting started

NB: This is nbdev v2, a major upgrade of nbdev. Whilst the differences
to nbdev1 aren’t huge, it does require some changes. The old version
docs are at nbdev1.fast.ai. You can use
version-pinning in settings.ini (i.e 'nbdev<2') to stop nbdev from
upgrading. To upgrade, follow the migration
tutorial.

nbdev is a system for exploratory programming. Simply write
notebooks with lightweight markup and get high-quality documentation,
tests, continuous integration, and packaging for free!

nbdev makes debugging and refactoring your code much easier than in
traditional programming environments since you always have live objects
at your fingertips. nbdev also promotes software engineering best
practices because tests and documentation are first class.

• Documentation is automatically generated using
  Quarto and hosted on GitHub
  Pages. Docs support LaTeX, are
  searchable, and are automatically hyperlinked (including
  out-of-the-box support for many packages via
  nbdev-index). You also
  have fine-grained control over how cells are displayed.
• Publish packages to PyPI and conda as well as tools to simplify
  package releases. Python best practices are automatically followed,
  for example, only exported objects are included in __all__
• Two-way sync between notebooks and plaintext source code
  allowing you to use your IDE for code navigation or quick edits.
• Tests written as ordinary notebook cells are run in parallel
  with a single command. You have fine-grained control over which
  tests are run.
• Continuous integration out-of-the-box with GitHub
  Actions that run your tests on
  each push and rebuild docs on each merge.
• Git-friendly notebooks with tools that clean unwanted metadata
  and render merge conflicts in a human-readable format.
• … and much more!

Install

With pip:

pip install nbdev

With conda:

conda install -c fastai nbdev

Note that nbdev must be installed into the same Python environment
that you use for both Jupyter and your project.

How to use nbdev

The best way to learn to use nbdev is to complete one of these tutorials
(we suggest replicating each step to solidify your understanding):

• Written tutorial

Video step-by-step walkthru (to view full screen, click the little
square in the bottom right of the video; to view in a separate Youtube
window, click the Youtube logo):

(There’s an alternate version of the
walkthru avaialable with the coding
sections sped up using the unsilence python library – it’s 27 minutes
faster, but it’s be harder to follow along with.)

You can run nbdev_help from the terminal to see the full list of
available commands:

!nbdev_help

nbdev_bump_version              Increment version in settings.ini by one
nbdev_clean                     Clean all notebooks in `fname` to avoid merge conflicts
nbdev_conda                     Create and upload a conda package
nbdev_create_config             Create a config file
nbdev_deploy                    Deploy docs to GitHub Pages
nbdev_docs                      Generate docs
nbdev_export                    Export notebooks in `path` to Python modules
nbdev_filter                    A notebook filter for Quarto
nbdev_fix                       Create working notebook from conflicted notebook `nbname`
nbdev_ghp_deploy                Deploy docs in `doc_path` from settings.ini to GitHub Pages
nbdev_help                      Show help for all console scripts
nbdev_install                   Install Quarto and the current library
nbdev_install_hooks             Install git hooks to clean and trust notebooks automatically
nbdev_install_quarto            Install latest Quarto on macOS or Linux, prints instructions for Windows
nbdev_migrate_directives        Convert all directives in `fname` from v1 to v2
nbdev_new                       Create a new project from the current git repo
nbdev_prepare                   Export, test, and clean notebooks
nbdev_preview                   Start a local docs webserver
nbdev_pypi                      Create and upload Python package to PyPI
nbdev_quarto                    Create Quarto docs and README.md
nbdev_readme                    Render README.md from index.ipynb
nbdev_release                   Release both conda and PyPI packages
nbdev_sidebar                   Create sidebar.yml
nbdev_test                      Test in parallel notebooks matching `fname`, passing along `flags`
nbdev_trust                     Trust notebooks matching `fname`
nbdev_update                    Propagate change in modules matching `fname` to notebooks that created them

FAQ

Q: Someone told me not to use notebooks for “serious” software development!

Watch this video. Don’t worry, we still
get this too, despite having used nbdev for a wide range of “very
serious” software projects over the last three years, including deep
learning libraries, API
clients, Python language
extensions, terminal user
interfaces, and more!

nbdev in the wild

fastai ecosystem

nbdev has been used to build innovative software in the fastai
ecosystem, including the fastai deep learning
library which implements a unique layered API and callback
system, and
fastcore, which supercharges Python
leveraging its dynamic nature. Furthermore, nbdev allows a very small
number of developers to maintain and grow a large
ecosystem of software engineering, data
science, machine learning, and devops tools.

Contributing

If you want to contribute to nbdev, be sure to review the
contributions
guidelines.
This project adheres to fastai’s code of
conduct.
By participating, you are expected to uphold this code. In general, we
strive to abide by generally accepted best practices in open-source
software development.

Make sure you have nbdev’s git hooks installed by running
nbdev_install_hooks
in the cloned repository.

Copyright

Copyright © 2019 onward fast.ai, Inc. Licensed under the Apache License,
Version 2.0 (the “License”); you may not use this project’s files except
in compliance with the License. A copy of the License is provided in the
LICENSE file in this repository.