Console commands added by the nbdev library

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.

Migrate from comment flags to magic flags

Migrating notebooks

Run nbdev_upgrade from the command line to update code cells in notebooks that use comment flags like

#export special.module

to use magic flags

%nbdev_export special.module

To make the magic flags work, nbdev_upgrade might need to add a new code cell to the top of the notebook

from nbdev import *

Hiding the from nbdev import * cell

nbdev does not treat from nbdev import * as special, but this cell can be hidden from the docs by combining it with %nbdev_default_export. e.g.

from nbdev import *
%nbdev_default_export my_module

this works because nbdev will hide any code cell containing the %nbdev_default_export flag.

If you don't need %nbdev_default_export in your notebook you can: use the hide input jupyter extension or edit cell metadata to include "hide_input": true

Add css for "collapse" components

If you want to use collapsable cells in your HTML docs, you need to style the details tag in customstyles.css. _add_collapse_css will do this for you, if the details tag is not already styled.

Upgrading existing nbdev projects to use new features


nbdev_upgrade(migrate2magic:"Migrate all notebooks in nbs_path to use magic flags"=True, add_collapse_css:"Add css for "#collapse" components"=True)

Update an existing nbdev project to use the latest features

  • migrate2magic reads all notebooks in nbs_path and migrates them in-place
  • add_collapse_css updates customstyles.css so that "collapse" components can be used in HTML pages


nbdev_build_lib(fname:"A notebook name or glob to convert"=None)

Export notebooks matching fname to python modules

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(fname:"A notebook name or glob to convert"=None)

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

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.



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

Extracting tests


nbdev_test_nbs(fname:"A notebook name or glob to convert"=None, flags:"Space separated list of flags"=None, n_workers:"Number of workers to use"=None, verbose:"Print errors along the way"=True, timing:"Timing each notebook to see the ones are slow"=False)

Test in parallel the notebooks matching fname, passing along flags

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

The following functions complete the ones in export2html to fully build the documentation of your library.



Convert the index notebook to


nbdev_build_docs(fname:"A notebook name or glob to convert"=None, force_all:"Rebuild even notebooks that haven't changed"=False, mk_readme:"Also convert the index notebook to README"=True, n_workers:"Number of workers to use"=None)

Build the documentation by converting notebooks mathing fname to html

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(fname:"A notebook file name to convert", dest:"The destination folder"='.', img_path:"Folder to export images to"='', jekyll:"To use jekyll metadata for your markdown file or not"=False)

Convert the notebook in fname to a markdown file


nbdev_detach(path_nb:"Path to notebook", dest:"Destination folder"='', use_img:"Convert markdown images to img tags"=False)

Export cell attachments to dest and update references

Other utils


nbdev_read_nbs(fname:"A notebook name or glob to convert"=None)

Check all notebooks matching fname can be opened

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


nbdev_trust_nbs(fname:"A notebook name or glob to convert"=None, force_all:"Trust even notebooks that haven't changed"=False)

Trust noteboks matching fname

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(fname:"A notebook filename to fix", fast:"Fast fix: automatically fix the merge conflicts in outputs or metadata"=True, trust_us:"Use local outputs/metadata when fast mergning"=True)

Fix merge conflicts in notebook fname

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 sucessful.

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(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(part:"Part of version to bump"=2)

Increment version in by one


nbdev_conda_package(path:"Path where package will be created"='conda', do_build:"Run conda build step"=True, build_args:"Additional args (as str) to send to conda build"='', do_upload:"Run anaconda upload step"=True, upload_user:"Optional user to upload package to"=None)

Create a meta.yaml file ready to be built into a package, and optionally build and upload it

To build and upload a conda package, cd to the root of your repo, and then:


Or to do things more manually:

nbdev_conda_package --do_build false
cd conda
conda build {name}
anaconda upload $CONDA_PREFIX/conda-bld/noarch/{name}-{ver}-*.tar.bz2

Add --debug to the conda build command to debug any problems that occur. Note that the build step takes a few minutes. Add -u {org_name} to the anaconda upload command if you wish to upload to an organization, or pass upload_user to nbdev_conda_package.

NB: you need to first of all upload your package to PyPi, before creating the conda package. Use make pypi to do this manually with nbdev, or make release to make both pip and conda packages, and update your version number.

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


nbdev_new(name:"A directory to create the project in", template_git_repo:"url to template repo"='')

Create a new nbdev project with a given name.

nbdev_new is a command line tool that creates a new nbdev project based on the nbdev_template repo. You can use a custom template by passing in template_git_repo. It'll initialize a new git repository and commit the new project.

After you run nbdev_new, please edit settings.ini and run nbdev_build_lib.