nbformat

nbformat defines and implements the Jupyter Notebook file format (.ipynb) — the versioned JSON schema describing cells, outputs, and metadata that every notebook is stored as. It provides the canonical read()/write() functions, JSON Schema-based validation, and converters between historical format versions (v1 through the current v4.5) that every other Jupyter tool relies on rather than reimplementing.

Because nearly all notebook-facing tools (JupyterLab, nbconvert, nbclient, Jupytext, papermill) need to parse or produce .ipynb files, nbformat acts as the shared, authoritative dependency that keeps notebook files interoperable across the whole ecosystem and across notebooks created years apart with older format versions.

What You Get

• nbformat.read()/nbformat.write() for loading and saving .ipynb files as Python objects
• NotebookNode - a dict-like, attribute-accessible object model for notebook cells and metadata
• JSON Schema-based validate() to check a notebook against its declared format version
• nbformat.v1 through v4 subpackages implementing every historical notebook format version
• converter.py utilities to upgrade older-format notebooks to the current version
• Digital signing (sign.py) to mark trusted notebooks so their outputs render without re-execution warnings

Common Use Cases

• Reading or writing .ipynb files programmatically from a script, converter, or CI pipeline
• Validating that a generated or hand-edited notebook file conforms to the Jupyter format schema
• Upgrading legacy notebooks (v1-v3) to the current v4 format before further processing
• Building notebook-manipulating tools (linters, converters, diffing tools) on a stable, shared object model instead of raw JSON

Under The Hood

Architecture - reader.py and converter.py inspect a notebook JSON blob’s declared nbformat/nbformat_minor version and dispatch to the matching versioned subpackage (nbformat/v1 through nbformat/v4), each of which defines its own JSON Schema and a NotebookNode construction path; validator.py runs the appropriate JSON Schema against the parsed structure, and converter.py implements the upgrade chain that walks a notebook forward through intermediate format versions to the current one. Tech Stack - pure Python (~2,600 lines) built on jsonschema for schema validation, traitlets/jupyter_core for path and config conventions, and fastjsonschema as an optional faster validator; the repo also ships a thin index.js/package.json exposing the JSON Schemas as an npm package for JavaScript-side notebook tooling. Code Quality - the tests/ directory includes a large corpus of real and deliberately invalid .ipynb fixture files (invalid.ipynb, invalid_cell_id.ipynb, v4_5_invalid_metadata.ipynb, etc.) exercised by test_validator.py, test_convert.py, test_reader.py, and per-version test subdirectories (tests/v1 through tests/v4), giving strong regression coverage across the format’s full history; the package ships py.typed for typed consumption. API Design - the public surface centers on two functions (read, write) and a NotebookNode that behaves like both a dict and an object with attribute access, minimizing friction for tools that just need to load/save notebooks, while the versioned validation/conversion machinery is kept internal so most consumers never need to reason about format-version history directly.