Configuration options¶
Configuration options may be set in a file, ~/.jupyter/jupyter_nbconvert_config.py,
or at the command line when starting nbconvert, i.e. jupyter nbconvert --Application.log_level=10.
The most specific setting will always be used. For example, the LatexExporter and the HTMLExporter both inherit from TemplateExporter. With the following config
c.TemplateExporter.exclude_input_prompt = False # The default
c.PDFExporter.exclude_input_prompt = True
input prompts will not appear when converting to PDF, but they will appear when exporting to HTML.
CLI Flags and Aliases¶
When using Nbconvert from the command line, a number of aliases and flags are defined as shortcuts to configuration options for convience.
The following flags are defined:
- debug
set log level to logging.DEBUG (maximize logging output)
Long Form: {‘Application’: {‘log_level’: 10}}
- generate-config
generate default config file
Long Form: {‘JupyterApp’: {‘generate_config’: True}}
- y
Answer yes to any questions instead of prompting.
Long Form: {‘JupyterApp’: {‘answer_yes’: True}}
- execute
Execute the notebook prior to export.
Long Form: {‘ExecutePreprocessor’: {‘enabled’: True}}
- allow-errors
Continue notebook execution even if one of the cells throws an error and include the error message in the cell output (the default behaviour is to abort conversion). This flag is only relevant if ‘–execute’ was specified, too.
Long Form: {‘ExecutePreprocessor’: {‘allow_errors’: True}}
- stdin
read a single notebook file from stdin. Write the resulting notebook with default basename ‘notebook.*’
Long Form: {‘NbConvertApp’: {‘from_stdin’: True}}
- stdout
Write notebook output to stdout instead of files.
Long Form: {‘NbConvertApp’: {‘writer_class’: ‘StdoutWriter’}}
- inplace
Run nbconvert in place, overwriting the existing notebook (only relevant when converting to notebook format)
Long Form: {‘NbConvertApp’: {‘use_output_suffix’: False, ‘export_format’: ‘notebook’}, ‘FilesWriter’: {‘build_directory’: ‘’}}
- clear-output
Clear output of current file and save in place, overwriting the existing notebook.
Long Form: {‘NbConvertApp’: {‘use_output_suffix’: False, ‘export_format’: ‘notebook’}, ‘FilesWriter’: {‘build_directory’: ‘’}, ‘ClearOutputPreprocessor’: {‘enabled’: True}}
- no-prompt
Exclude input and output prompts from converted document.
Long Form: {‘TemplateExporter’: {‘exclude_input_prompt’: True, ‘exclude_output_prompt’: True}}
- no-input
Exclude input cells and output prompts from converted document. This mode is ideal for generating code-free reports.
Long Form: {‘TemplateExporter’: {‘exclude_output_prompt’: True, ‘exclude_input’: True}}
The folowing aliases are defined:
log-level (Application.log_level)
config (JupyterApp.config_file)
to (NbConvertApp.export_format)
template (TemplateExporter.template_file)
writer (NbConvertApp.writer_class)
post (NbConvertApp.postprocessor_class)
output (NbConvertApp.output_base)
output-dir (FilesWriter.build_directory)
reveal-prefix (SlidesExporter.reveal_url_prefix)
nbformat (NotebookExporter.nbformat_version)
App Options¶
- Application.log_datefmtUnicode
Default:
'%Y-%m-%d %H:%M:%S'The date format used by logging formatters for %(asctime)s
- Application.log_formatUnicode
Default:
'[%(name)s]%(highlevel)s %(message)s'The Logging format template
- Application.log_level0|10|20|30|40|50|’DEBUG’|’INFO’|’WARN’|’ERROR’|’CRITICAL’
Default:
30Set the log level by value or name.
- JupyterApp.answer_yesBool
Default:
FalseAnswer yes to any prompts.
- JupyterApp.config_fileUnicode
Default:
''Full path of a config file.
- JupyterApp.config_file_nameUnicode
Default:
''Specify a config file to load.
- JupyterApp.generate_configBool
Default:
FalseGenerate default config file.
- NbConvertApp.export_formatUnicode
Default:
'html'The export format to be used, either one of the built-in formats [‘asciidoc’, ‘custom’, ‘html’, ‘latex’, ‘markdown’, ‘notebook’, ‘pdf’, ‘python’, ‘rst’, ‘script’, ‘slides’] or a dotted object name that represents the import path for an Exporter class
- NbConvertApp.from_stdinBool
Default:
Falseread a single notebook from stdin.
- NbConvertApp.ipywidgets_base_urlUnicode
Default:
'https://unpkg.com/'URL base for ipywidgets package
- NbConvertApp.notebooksList
Default:
[]List of notebooks to convert. Wildcards are supported. Filenames passed positionally will be added to the list.
- NbConvertApp.output_baseUnicode
Default:
''overwrite base name use for output files. can only be used when converting one notebook at a time.
- NbConvertApp.output_files_dirUnicode
Default:
'{notebook_name}_files'Directory to copy extra files (figures) to. ‘{notebook_name}’ in the string will be converted to notebook basename.
- NbConvertApp.postprocessor_classDottedOrNone
Default:
''PostProcessor class used to write the results of the conversion
- NbConvertApp.use_output_suffixBool
Default:
TrueWhether to apply a suffix prior to the extension (only relevant when converting to notebook format). The suffix is determined by the exporter, and is usually ‘.nbconvert’.
- NbConvertApp.writer_classDottedObjectName
Default:
'FilesWriter'Writer class used to write the results of the conversion
Exporter Options¶
- Exporter.default_preprocessorsList
Default:
['nbconvert.preprocessors.TagRemovePreprocessor', 'nbconvert....List of preprocessors available by default, by name, namespace, instance, or type.
- Exporter.file_extensionFilenameExtension
Default:
'.txt'Extension of the file that should be written to disk
- Exporter.preprocessorsList
Default:
[]List of preprocessors, by name or namespace, to enable.
- TemplateExporter.exclude_code_cellBool
Default:
FalseThis allows you to exclude code cells from all templates if set to True.
- TemplateExporter.exclude_inputBool
Default:
FalseThis allows you to exclude code cell inputs from all templates if set to True.
- TemplateExporter.exclude_input_promptBool
Default:
FalseThis allows you to exclude input prompts from all templates if set to True.
- TemplateExporter.exclude_markdownBool
Default:
FalseThis allows you to exclude markdown cells from all templates if set to True.
- TemplateExporter.exclude_outputBool
Default:
FalseThis allows you to exclude code cell outputs from all templates if set to True.
- TemplateExporter.exclude_output_promptBool
Default:
FalseThis allows you to exclude output prompts from all templates if set to True.
- TemplateExporter.exclude_rawBool
Default:
FalseThis allows you to exclude raw cells from all templates if set to True.
- TemplateExporter.exclude_unknownBool
Default:
FalseThis allows you to exclude unknown cells from all templates if set to True.
- TemplateExporter.filtersDict
Default:
{}Dictionary of filters, by name and namespace, to add to the Jinja environment.
- TemplateExporter.raw_mimetypesList
Default:
[]formats of raw cells to be included in this Exporter’s output.
- TemplateExporter.template_extensionUnicode
Default:
'.tpl'No description
- TemplateExporter.template_fileUnicode
Default:
''Name of the template file to use
- TemplateExporter.template_pathList
Default:
['.']No description
- HTMLExporter.anchor_link_textUnicode
Default:
'¶'The text used as the text for anchor links.
- LatexExporter.template_extensionUnicode
Default:
'.tplx'No description
- NotebookExporter.nbformat_version1|2|3|4
Default:
4The nbformat version to write. Use this to downgrade notebooks.
- PDFExporter.bib_commandList
Default:
['bibtex', '{filename}']Shell command used to run bibtex.
- PDFExporter.latex_commandList
Default:
['xelatex', '{filename}', '-quiet']Shell command used to compile latex.
- PDFExporter.latex_countInt
Default:
3How many times latex will be called.
- PDFExporter.verboseBool
Default:
FalseWhether to display the output of latex commands.
- SlidesExporter.font_awesome_urlUnicode
Default:
'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/cs...URL to load font awesome from.
Defaults to loading from cdnjs.
- SlidesExporter.jquery_urlUnicode
Default:
'https://cdnjs.cloudflare.com/ajax/libs/jquery/2.0.3/jquery.m...URL to load jQuery from.
Defaults to loading from cdnjs.
- SlidesExporter.require_js_urlUnicode
Default:
'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/req...URL to load require.js from.
Defaults to loading from cdnjs.
- SlidesExporter.reveal_scrollBool
Default:
FalseIf True, enable scrolling within each slide
- SlidesExporter.reveal_themeUnicode
Default:
'simple'Name of the reveal.js theme to use.
We look for a file with this name under
reveal_url_prefix/css/theme/reveal_theme.css.https://github.com/hakimel/reveal.js/tree/master/css/theme has list of themes that ship by default with reveal.js.
- SlidesExporter.reveal_transitionUnicode
Default:
'slide'Name of the reveal.js transition to use.
The list of transitions that ships by default with reveal.js are: none, fade, slide, convex, concave and zoom.
- SlidesExporter.reveal_url_prefixUnicode
Default:
''The URL prefix for reveal.js (version 3.x). This defaults to the reveal CDN, but can be any url pointing to a copy of reveal.js.
For speaker notes to work, this must be a relative path to a local copy of reveal.js: e.g., “reveal.js”.
If a relative path is given, it must be a subdirectory of the current directory (from which the server is run).
See the usage documentation (https://nbconvert.readthedocs.io/en/latest/usage.html#reveal-js-html-slideshow) for more details.
Writer Options¶
- WriterBase.filesList
Default:
[]List of the files that the notebook references. Files will be included with written output.
- FilesWriter.build_directoryUnicode
Default:
''Directory to write output(s) to. Defaults to output to the directory of each notebook. To recover previous default behaviour (outputting to the current working directory) use . as the flag value.
- FilesWriter.relpathUnicode
Default:
''When copying files that the notebook depends on, copy them in relation to this path, such that the destination filename will be os.path.relpath(filename, relpath). If FilesWriter is operating on a notebook that already exists elsewhere on disk, then the default will be the directory containing that notebook.
Preprocessor Options¶
- Preprocessor.enabledBool
Default:
FalseNo description
- CSSHTMLHeaderPreprocessor.highlight_classUnicode
Default:
'.highlight'CSS highlight class identifier
- CSSHTMLHeaderPreprocessor.styleUnicode
Default:
'default'Name of the pygments style to use
- ClearOutputPreprocessor.remove_metadata_fieldsSet
Default:
{'scrolled', 'collapsed'}No description
- ConvertFiguresPreprocessor.from_formatUnicode
Default:
''Format the converter accepts
- ConvertFiguresPreprocessor.to_formatUnicode
Default:
''Format the converter writes
- ExecutePreprocessor.allow_errorsBool
Default:
FalseIf False (default), when a cell raises an error the execution is stopped and a CellExecutionError is raised. If True, execution errors are ignored and the execution is continued until the end of the notebook. Output from exceptions is included in the cell output in both cases.
- ExecutePreprocessor.force_raise_errorsBool
Default:
FalseIf False (default), errors from executing the notebook can be allowed with a raises-exception tag on a single cell, or the allow_errors configurable option for all cells. An allowed error will be recorded in notebook output, and execution will continue. If an error occurs when it is not explicitly allowed, a CellExecutionError will be raised. If True, CellExecutionError will be raised for any error that occurs while executing the notebook. This overrides both the allow_errors option and the raises-exception cell tag.
- ExecutePreprocessor.interrupt_on_timeoutBool
Default:
FalseIf execution of a cell times out, interrupt the kernel and continue executing other cells rather than throwing an error and stopping.
- ExecutePreprocessor.iopub_timeoutInt
Default:
4The time to wait (in seconds) for IOPub output. This generally doesn’t need to be set, but on some slow networks (such as CI systems) the default timeout might not be long enough to get all messages.
- ExecutePreprocessor.ipython_hist_fileUnicode
Default:
':memory:'Path to file to use for SQLite history database for an IPython kernel.
The specific value :memory: (including the colon at both end but not the back ticks), avoids creating a history file. Otherwise, IPython will create a history file for each kernel.
When running kernels simultaneously (e.g. via multiprocessing) saving history a single SQLite file can result in database errors, so using :memory: is recommended in non-interactive contexts.
- ExecutePreprocessor.kernel_manager_classType
Default:
'builtins.object'The kernel manager class to use.
- ExecutePreprocessor.kernel_nameUnicode
Default:
''Name of kernel to use to execute the cells. If not set, use the kernel_spec embedded in the notebook.
- ExecutePreprocessor.raise_on_iopub_timeoutBool
Default:
FalseIf False (default), then the kernel will continue waiting for iopub messages until it receives a kernel idle message, or until a timeout occurs, at which point the currently executing cell will be skipped. If True, then an error will be raised after the first timeout. This option generally does not need to be used, but may be useful in contexts where there is the possibility of executing notebooks with memory-consuming infinite loops.
- ExecutePreprocessor.shutdown_kernel‘graceful’|’immediate’
Default:
'graceful'If graceful (default), then the kernel is given time to clean up after executing all cells, e.g., to execute its atexit hooks. If immediate, then the kernel is signaled to immediately terminate.
- ExecutePreprocessor.startup_timeoutInt
Default:
60The time to wait (in seconds) for the kernel to start. If kernel startup takes longer, a RuntimeError is raised.
- ExecutePreprocessor.store_widget_stateBool
Default:
TrueIf True (default), then the state of the Jupyter widgets created at the kernel will be stored in the metadata of the notebook.
- ExecutePreprocessor.timeoutInt
Default:
30The time to wait (in seconds) for output from executions. If a cell execution takes longer, an exception (TimeoutError on python 3+, RuntimeError on python 2) is raised.
None or -1 will disable the timeout. If timeout_func is set, it overrides timeout.
- ExecutePreprocessor.timeout_funcAny
Default:
NoneA callable which, when given the cell source as input, returns the time to wait (in seconds) for output from cell executions. If a cell execution takes longer, an exception (TimeoutError on python 3+, RuntimeError on python 2) is raised.
Returning None or -1 will disable the timeout for the cell. Not setting timeout_func will cause the preprocessor to default to using the timeout trait for all cells. The timeout_func trait overrides timeout if it is not None.
- ExtractOutputPreprocessor.extract_output_typesSet
Default:
{'image/svg+xml', 'application/pdf', 'image/jpeg', 'image/png'}No description
- ExtractOutputPreprocessor.output_filename_templateUnicode
Default:
'{unique_key}_{cell_index}_{index}{extension}'No description
- HighlightMagicsPreprocessor.languagesDict
Default:
{}Syntax highlighting for magic’s extension languages. Each item associates a language magic extension such as %%R, with a pygments lexer such as r.
- LatexPreprocessor.styleUnicode
Default:
'default'Name of the pygments style to use
- RegexRemovePreprocessor.patternsList
Default:
[]No description
- SVG2PDFPreprocessor.commandUnicode
Default:
''The command to use for converting SVG to PDF
This string is a template, which will be formatted with the keys to_filename and from_filename.
The conversion call must read the SVG from {from_filename}, and write a PDF to {to_filename}.
- SVG2PDFPreprocessor.inkscapeUnicode
Default:
''The path to Inkscape, if necessary
- TagRemovePreprocessor.remove_all_outputs_tagsSet
Default:
set()Tags indicating cells for which the outputs are to be removed,matches tags in cell.metadata.tags.
- TagRemovePreprocessor.remove_cell_tagsSet
Default:
set()Tags indicating which cells are to be removed,matches tags in cell.metadata.tags.
- TagRemovePreprocessor.remove_input_tagsSet
Default:
set()Tags indicating cells for which input is to be removed,matches tags in cell.metadata.tags.
- TagRemovePreprocessor.remove_single_output_tagsSet
Default:
set()Tags indicating which individual outputs are to be removed,matches output i tags in cell.outputs[i].metadata.tags.
Postprocessor Options¶
- ServePostProcessor.browserUnicode
Default:
''Specify what browser should be used to open slides. See https://docs.python.org/3/library/webbrowser.html#webbrowser.register to see how keys are mapped to browser executables. If not specified, the default browser will be determined by the webbrowser standard library module, which allows setting of the BROWSER environment variable to override it.
- ServePostProcessor.ipUnicode
Default:
'127.0.0.1'The IP address to listen on.
- ServePostProcessor.open_in_browserBool
Default:
TrueShould the browser be opened automatically?
- ServePostProcessor.portInt
Default:
8000port for the server to listen on.
- ServePostProcessor.reveal_cdnUnicode
Default:
'https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.5.0'URL for reveal.js CDN.
- ServePostProcessor.reveal_prefixUnicode
Default:
'reveal.js'URL prefix for reveal.js
Other Options¶
- NbConvertBase.default_languageUnicode
Default:
'ipython'Deprecated default highlight language as of 5.0, please use language_info metadata instead
- NbConvertBase.display_data_priorityList
Default:
['text/html', 'application/pdf', 'text/latex', 'image/svg+xml...An ordered list of preferred output type, the first encountered will usually be used when converting discarding the others.