Get Started#

myst-nb is distributed as a Python package and requires no non-Python dependencies.

Use pip to install myst-nb:

pip install myst-nb

You can use the mystnb-quickstart CLI to quickly create an example Sphinx + MyST-NB project:

mystnb-quickstart my_project/docs/

or simply add myst_nb to your existing Sphinx configuration:

extensions = [
    ...,
    "myst_nb"
]

By default, MyST-NB will now parse both markdown (.md) and notebooks (.ipynb).

Begin authoring your content

Once you have finished authoring your content, you can now use the sphinx-build CLI to build your documentation, e.g.

sphinx-build -nW --keep-going -b html docs/ docs/_build/html

Tip

MyST-NB is parallel-friendly, so you can also distribute the build (and execution of notebooks) over N processes with: sphinx-build -j 4

The execution environment is the same as your Sphinx environment

Your Sphinx build shares the same environment with the notebooks you execute during a build. Ensure that you call the correct sphinx-build command when building your documentation, or the environment needed to run the notebooks may not be correct. This often happens if you see an Extension error in the build log, or an error from jupyter-cache.