Jupyter Notebook Format

Warnings

• breaking nbformat 5.0.0 dropped support for Python 2.x. It now requires Python 3.5+ (currently >= 3.8). If you are on an older Python 3 version, check the specific `nbformat` 5.x patch release for minimum Python requirements.
  Fix: Upgrade your Python environment to Python 3.8 or newer.
• deprecated The `nbformat.current` module is deprecated. It was intended for backward compatibility but can lead to confusion regarding notebook versions.
  Fix: Directly import from specific version modules like `nbformat.v4` (e.g., `from nbformat.v4 import new_notebook`) for programmatic notebook creation and manipulation, and use `nbformat.read()` or `nbformat.write()` for file I/O.
• gotcha The `validate()` function in nbformat 5.5.0 and later no longer attempts to fix notebook errors during validation. It will now raise a `ValidationError` for invalid notebooks rather than silently modifying them.
  Fix: Ensure your notebooks strictly conform to the expected schema *before* calling `validate()`. If you need to upgrade older notebooks, use `nbformat.convert(nb_node, to_version=4)` explicitly, or rely on `nbformat.read(..., as_version=4)` which performs conversion if needed.
• gotcha When reading or writing notebooks, `nbformat.NO_CONVERT` can be passed to the `as_version` or `version` parameters to prevent any version conversion. If you omit `version` during writing, the notebook's own version will be used without conversion.
  Fix: Be explicit about desired notebook format versions. If you want to ensure a specific output format, always set `version=4` (or another target version) in `nbformat.write()`. Similarly, when reading, use `as_version=4` if you want the returned object to be converted to that version.

Install

• pip install nbformat Install nbformat

Imports

• nbformat

  import nbformat

• new_notebook

  from nbformat.v4 import new_notebook

  `nbformat.current` is deprecated since before nbformat 3.0. Always import from specific version modules like `nbformat.v4` for composing new notebooks.

Quickstart

This quickstart demonstrates how to create a new Jupyter Notebook programmatically, add markdown and code cells, save it to a `.ipynb` file, and then read the content of an existing notebook. It uses the `nbformat.v4` module for creating notebook components, ensuring compatibility with the current Jupyter Notebook format specification version 4.

import nbformat
from nbformat.v4 import new_notebook, new_markdown_cell, new_code_cell
import os

# 1. Create a new notebook
nb = new_notebook()

# Add a markdown cell
nb.cells.append(new_markdown_cell("## My First Notebook (nbformat)"))

# Add a code cell
code_cell_content = "print('Hello from nbformat!')\nx = 1 + 2\nprint(f'The sum is: {x}')"
nb.cells.append(new_code_cell(code_cell_content))

# Define output path
notebook_filename = 'example_notebook.ipynb'

# 2. Write the notebook to a file
with open(notebook_filename, 'w', encoding='utf-8') as f:
    nbformat.write(nb, f)
print(f"Notebook '{notebook_filename}' created successfully.")

# 3. Read an existing notebook
read_nb = None
if os.path.exists(notebook_filename):
    with open(notebook_filename, 'r', encoding='utf-8') as f:
        # Specify as_version=4 to ensure it's read as the V4 format
        read_nb = nbformat.read(f, as_version=4)
    print(f"\nNotebook '{notebook_filename}' read successfully.")
    print(f"Notebook format version: {read_nb.nbformat}.{read_nb.nbformat_minor}")
    for i, cell in enumerate(read_nb.cells):
        print(f"\n--- Cell {i+1} ({cell.cell_type}) ---")
        print(cell.source)
else:
    print(f"Error: '{notebook_filename}' not found for reading.")