nbdev comes with the following commands. To use any of them, you must be in one of the subfolders of your project: they will search for the settings.ini recursively in the parent directory but need to access it to be able to work. Their names all begin with nbdev so you can easily get a list with tab completion.

• nbdev_build_docs builds the documentation from the notebooks
• nbdev_build_lib builds the library from the notebooks
• nbdev_bump_version increments version in settings.py by one
• nbdev_clean_nbs removes all superfluous metadata form the notebooks, to avoid merge conflicts
• nbdev_detach exports cell attachments to dest and updates references
• nbdev_diff_nbs gives you the diff between the notebooks and the exported library
• nbdev_fix_merge will fix merge conflicts in a notebook file
• nbdev_install_git_hooks installs the git hooks that use the last two command automatically on each commit/merge
• nbdev_nb2md converts a notebook to a markdown file
• nbdev_new creates a new nbdev project
• nbdev_read_nbs reads all notebooks to make sure none are broken
• nbdev_test_nbs runs tests in notebooks
• nbdev_trust_nbs trusts all notebooks (so that the HTML content is shown)
• nbdev_update_lib propagates any change in the library back to the notebooks

Navigating from notebooks to script and back

nbdev_build_lib[source]

nbdev_build_lib(fname:str=None, bare:store_true=False)

Export notebooks matching fname to python modules

	Type	Default	Details
fname	str	None	A notebook name or glob to convert
bare	store_true	False	Omit nbdev annotation comments (may break some functionality).

By default (fname left to None), the whole library is built from the notebooks in the lib_folder set in your settings.ini.

nbdev_update_lib[source]

nbdev_update_lib(fname:str=None, silent:bool_arg=False)

Propagates any change in the modules matching fname to the notebooks that created them

	Type	Default	Details
fname	str	None	A python filename or glob to convert
silent	bool_arg	False	Dont print results

By default (fname left to None), the whole library is treated. Note that this tool is only designed for small changes such as typo or small bug fixes. You can't add new cells in notebook from the library.

nbdev_diff_nbs[source]

nbdev_diff_nbs()

Prints the diff between an export of the library in notebooks and the actual modules

Running tests

nbdev_test_nbs[source]

nbdev_test_nbs(fname:str=None, flags:str=None, n_workers:int=None, verbose:bool_arg=True, timing:bool=False, pause:float=0.5)

Test in parallel the notebooks matching fname, passing along flags

	Type	Default	Details
fname	str	None	A notebook name or glob to convert
flags	str	None	Space separated list of flags
n_workers	int	None	Number of workers to use
verbose	bool_arg	True	Print errors along the way
timing	bool	False	Timing each notebook to see the ones are slow
pause	float	0.5	Pause time (in secs) between notebooks to avoid race conditions

By default (fname left to None), the whole library is tested from the notebooks in the lib_folder set in your settings.ini.

Building documentation

nbdev_build_docs[source]

nbdev_build_docs(fname:str=None, force_all:bool_arg=False, mk_readme:bool_arg=True, n_workers:int=None, pause:float=0.5)

Build the documentation by converting notebooks matching fname to html

	Type	Default	Details
fname	str	None	A notebook name or glob to convert
force_all	bool_arg	False	Rebuild even notebooks that havent changed
mk_readme	bool_arg	True	Also convert the index notebook to README
n_workers	int	None	Number of workers to use
pause	float	0.5	Pause time (in secs) between notebooks to avoid race conditions

By default (fname left to None), the whole documentation is build from the notebooks in the lib_folder set in your settings.ini, only converting the ones that have been modified since the their corresponding html was last touched unless you pass force_all=True. The index is also converted to make the README file, unless you pass along mk_readme=False.

nbdev_nb2md[source]

nbdev_nb2md(fname:str, dest:str='.', img_path:None='', jekyll:bool_arg=False)

Convert the notebook in fname to a markdown file

	Type	Default	Details
fname	str		A notebook file name to convert
dest	str	.	The destination folder
img_path	NoneType	""	Folder to export images to
jekyll	bool_arg	False	To use jekyll metadata for your markdown file or not

nbdev_detach[source]

nbdev_detach(path_nb:"Path to notebook", dest:str='', use_img:bool_arg=False, replace:bool_arg=True)

Export cell attachments to dest and update references

	Type	Default	Details
path_nb	<Path to notebook>		No Content
dest	str	""	Destination folder
use_img	bool_arg	False	Convert markdown images to img tags
replace	bool_arg	True	Write replacement notebook back to path_bn

Other utils

nbdev_read_nbs[source]

nbdev_read_nbs(fname:str=None)

Check all notebooks matching fname can be opened

	Type	Default	Details
fname	str	None	A notebook name or glob to convert

By default (fname left to None), the all the notebooks in lib_folder are checked.

nbdev_trust_nbs[source]

nbdev_trust_nbs(fname:str=None, force_all:bool=False)

Trust notebooks matching fname

	Type	Default	Details
fname	str	None	A notebook name or glob to convert
force_all	bool	False	Trust even notebooks that havent changed

By default (fname left to None), the all the notebooks in lib_folder are trusted. To speed things up, only the ones touched since the last time this command was run are trusted unless you pass along force_all=True.

nbdev_fix_merge[source]

nbdev_fix_merge(fname:str, fast:bool=True, trust_us:bool=True)

Fix merge conflicts in notebook fname

	Type	Default	Details
fname	str		A notebook filename to fix
fast	bool	True	Fast fix: automatically fix the merge conflicts in outputs or metadata
trust_us	bool	True	Use local outputs/metadata when fast merging

When you have merge conflicts after a git pull, the notebook file will be broken and won't open in jupyter notebook anymore. This command fixes this by changing the notebook to a proper json file again and add markdown cells to signal the conflict, you just have to open that notebook again and look for >>>>>>> to see those conflicts and manually fix them. The old broken file is copied with a .ipynb.bak extension, so is still accessible in case the merge wasn't successful.

Moreover, if fast=True, conflicts in outputs and metadata will automatically be fixed by using the local version if trust_us=True, the remote one if trust_us=False. With this option, it's very likely you won't have anything to do, unless there is a real conflict.

bump_version[source]

bump_version(version, part=2)

test_eq(bump_version('0.1.1'   ), '0.1.2')
test_eq(bump_version('0.1.1', 1), '0.2.0')

nbdev_bump_version[source]

nbdev_bump_version(part:int=2)

Increment version in settings.py by one

	Type	Default	Details
part	int	2	Part of version to bump

Git hooks

nbdev_install_git_hooks[source]

nbdev_install_git_hooks()

Install git hooks to clean/trust notebooks automatically

This command installs git hooks to make sure notebooks are cleaned before you commit them to GitHub and automatically trusted at each merge. To be more specific, this creates:

• an executable '.git/hooks/post-merge' file that contains the command nbdev_trust_nbs
• a .gitconfig file that uses nbev_clean_nbs has a filter/diff on all notebook files inside nbs_folder and a .gitattributes file generated in this folder (copy this file in other folders where you might have notebooks you want cleaned as well)

Starting a new project

extract_tgz[source]

extract_tgz(url, dest='.')

nbdev_new[source]

nbdev_new()

Create a new nbdev project from the current git repo

nbdev_new is a command line tool that creates a new nbdev project from the current directory, which must be a cloned git repo.

After you run nbdev_new, please check the contents of settings.ini look good, and then run nbdev_build_lib.

Using nbdev_new with private repos

nbdev_new attempts to find your repo on GitHub to determine your default branch. If your repo is private, you will need to set the environment variable GITHUB_TOKEN with a personal access token prior to running nbdev_new, or nbdev_new will use a default value instead.

You will receive a warning message if nbdev is not able to find your repo on GitHub that will tell you to replace the default branch name in settings.ini (which is the root of your repo).