This page was generated from doc/installation.ipynb. Interactive online version: . Download notebook.

# Installation

Note that some packages may be out of date. You can always get the newest `nbsphinx` release from PyPI (using `pip`). If you want to try the latest development version, have a look at the section Contributing.

## `nbsphinx` Packages

If you are using the `conda` package manager (e.g. with Miniforge or Miniconda), you can install `nbsphinx` from the conda-forge channel:

    conda install -c conda-forge nbsphinx

You can of course also install `nbsphinx` with `pip`, Python’s own package manager:

    python3 -m pip install nbsphinx

Depending on your Python installation, you may have to use `python` instead of `python3`. If you have installed the module already, you can use the `--upgrade` flag to get the newest release.

There are more packages available. For an overview, see repology.

## `nbsphinx` Prerequisites

Some of the aforementioned packages will install some of these prerequisites automatically, some of the things may be already installed on your computer anyway.

### Python

Of course you’ll need Python, because both Sphinx and `nbsphinx` are implemented in Python. There are many ways to get Python. If you don’t know which one is best for you, you can try Miniforge.

### Sphinx

You’ll need Sphinx as well, because `nbsphinx` is just a Sphinx extension and doesn’t do anything on its own.

If you use `conda`, you can get Sphinx from the conda-forge channel:

    conda install -c conda-forge sphinx

Alternatively, you can install it with `pip` (see below):

    python3 -m pip install Sphinx

### pip

Recent versions of Python already come with `pip` pre-installed. If you don’t have it, you can install it manually.

### pandoc

The stand-alone program pandoc is used to convert Markdown content to something Sphinx can understand. You have to install this program separately, ideally with your package manager. If you are using `conda`, you can install pandoc from the conda-forge channel:

    conda install -c conda-forge pandoc

If that doesn’t work out for you, have a look at `pandoc`’s installation instructions.

Note

The use of `pandoc` in `nbsphinx` is temporary, but will likely stay that way for a long time, see issue #36.

### Pygments Lexer for Syntax Highlighting

To get proper syntax highlighting in code cells, you’ll need an appropriate Pygments lexer. This of course depends on the programming language of your Jupyter notebooks (more specifically, the `pygments_lexer` metadata of your notebooks).

For example, if you use Python in your notebooks, you’ll have to have the `IPython` package installed, e.g. with

    conda install -c conda-forge ipython

or

    python3 -m pip install IPython

Note

If you are using Anaconda with the default channel and syntax highlighting in code cells doesn’t seem to work, you can try to install IPython from the `conda-forge` channel or directly with `pip`, or as a work-around, add `'IPython.sphinxext.ipython_console_highlighting'` to `extensions` in your `conf.py`.

For details, see Anaconda issue #1430 and nbsphinx issue #24.

### Jupyter Kernel

If you want to execute your notebooks during the Sphinx build process (see Controlling Notebook Execution), you need an appropriate Jupyter kernel installed.

For example, if you use Python, you should install the `ipykernel` package, e.g. with

    conda install -c conda-forge ipykernel

or

    python3 -m pip install ipykernel

If you created your notebooks yourself with Jupyter, it’s very likely that you have the right kernel installed already.

Note

If your automatic builds on https://readthedocs.org are failing due to an error like the one below, add `ipykernel` to `docs/requirements.txt` or `doc/environment.yml` to resolve.

    jupyter_client.kernelspec.nosuchkernel: no such kernel named python3