Jupyter configuration files¶
Jupyter configuration is based on the traitlets.config
module.
Essentially, each Jupyter application (e.g. notebook
, or
nbconvert
) has a number of configurable values which:
- have default values
- can be altered form their default by values read from configuration files,
which can be
a)
.json
static files b).py
config python scripts - can be overridden by command-line arguments
Jupyter config path¶
Jupyter applications search for configuration files in each directory in the jupyter config path. This path includes different locations in different operating systems, but you can use the root jupyter command to find a list of all jupyter paths, and look for the config section:
jupyter --paths
There are at least three configuration directories
- a per-user directory
- a directory in the
sys.prefix
directory for the python installation in use- a system-wide directory
Note that it is likely that to write to the system-wide config directory will require elevated (admin) privileges. This may also be true for the sys-prefix directory, depending on the python installation in use.
Finally, you can also specify a configuration file as a command line argument, for example:
jupyter notebook --config=/home/john/mystuff/jupyter_notebook_config.json
Note that this can change which filenames are searched for, as noted below.
Jupyter configuration filenames¶
Jupyter applications search the Jupyter config path for config files
with names derived from the application name, with file extension of either
.json
(loaded as json) or .py
(run as a python script).
For example, the jupyter notebook
application searches for config files
called jupyter_notebook_config
, while the jupyter nbconvert
application
searches for config files named jupyter_nbconvert_config
, with the file
extensions mentioned above.
In addition, all jupyter applications will load config files named
jupyter_config.json
or jupyter_config.py
.
Specifying a config file on the command line has the additional slightly subtle effect that it will also change the filename that the application searches for. For example, if I call the notebook using
jupyter notebook --config=/home/john/mystuff/special_config_ftw.json
then instead of searching the Jupyter config path for files named
jupyter_notebook_config
, the notebook application will search the config
path for other files also named special_config_ftw
, which can mean that the
normal config files get missed. As a result, it may be preferable to name any
custom config files with the standard filename for the jupyter application they
pertain to.
Config files edited by jupyter_contrib_nbextensions¶
The jupyter contrib nbextensions install
command edits some config files as
part of the install:
jupyter_notebook_config.json
is edited in order to:
- enable the jupyter_nbextensions_configurator. serverextension
- enable the
contrib_nbextensions_help_item
nbextension, which adds a link to readthedocs to the help menu
jupyter_nbconvert_config.json
is edited in order to:
- edit the nbconvert template path, adding the
jupyter_contrib_nbextensions.nbconvert_support
templates directory- add preprocessors
CodeFoldingPreprocessor
andPyMarkdownPreprocessor
from thejupyter_contrib_nbextensions.nbconvert_support
module