An .ipynb file is one JSON
object whose shape is fixed by the nbformat JSON schemas published by Project Jupyter.
Sources: the nbformat
format description
(nbformat 4) and the JSON schemas in the
jupyter/nbformat repository,
nbformat.v4.5.schema.json and nbformat.v3.schema.json.
Top level
| Key | Type | Meaning |
|---|---|---|
nbformat | integer | Major version: 4. A change means files are not backward compatible. |
nbformat_minor | integer | Minor version, 0 to 5. A reader keeps, but need not show, cell and output types it does not know. |
metadata | object | Notebook metadata; see below. |
cells | array | The cells, in order. |
Multi-line strings. Fields such as code input and text output may be stored either as one string or as an array of strings. Readers must accept both; nbformat’s own Python and JavaScript APIs always return one joined string.
Notebook metadata
| Key | Type | Meaning |
|---|---|---|
kernelspec | object | The kernel specification: name and display_name, both required strings. |
language_info | object | The kernel’s language: name (required), and in the schema codemirror_mode (string or object), file_extension, mimetype, pygments_lexer; the format description also shows version. |
authors | array | Objects with a required name; other keys allowed. |
title | string | The notebook’s title. |
orig_nbformat | integer | Major version the file had before it was converted. |
The schema allows other keys here. For cell metadata the description asks that
custom keys use a unique namespace, with official Jupyter keys under
jupyter.
Cells
| Key | Cell types | Meaning |
|---|---|---|
cell_type | all | "code", "markdown" or "raw". |
id | all (4.5) | 1 to 64 characters from A–Z a–z 0–9 - _, unique within the notebook. Required from nbformat 4.5; absent before it. |
metadata | all | Cell metadata; see below. |
source | all | The cell’s text (multi-line string). |
attachments | markdown, raw (4.1, backported to 4.0) | File names mapped to MIME bundles, e.g. {"test.png": {"image/png": "…"}}, so the Markdown can show them inline. |
execution_count | code | Integer, or null if never run. |
outputs | code | Array of outputs; see below. |
Markdown cells are GitHub-flavoured Markdown. A raw cell is not rendered in the
notebook; its metadata.format (a MIME type) names the nbconvert output it
goes into, other formats leave it out, and without it the cell goes into all. Code
cells require outputs and execution_count; no cell may
carry keys outside its list, but cell metadata may.
Cell metadata
| Key | Type | Meaning |
|---|---|---|
collapsed | boolean | Code cells: the output area is collapsed. |
scrolled | boolean or "auto" | Code cells: the output area scrolls. |
deletable | boolean | false: the cell cannot be deleted. |
editable | boolean | false: the cell cannot be edited (nor deleted). |
format | MIME type | Raw cells: the target format. |
name | string | A name, which should be unique in the notebook. |
tags | array of strings | Tags; no commas inside a tag. |
jupyter | object | source_hidden and outputs_hidden, booleans. |
execution | object | ISO 8601 times of the last run: iopub.execute_input (request received), iopub.status.busy (work started), shell.execute_reply (finished), iopub.status.idle (kernel idle again). |
Outputs
output_type | Keys | Meaning |
|---|---|---|
stream | name ("stdout" or "stderr"), text | Printed text. |
display_data | data (MIME bundle), metadata | Rich output from a display call. |
execute_result | data, metadata, execution_count | The value of the cell’s last expression. |
error | ename, evalue, traceback (array of strings) | An exception. |
metadata is keyed by MIME type, e.g.
{"image/png": {"width": 640, "height": 480}}; the key
isolated (boolean) asks for the output to be shown in an iframe.
MIME bundles
A MIME bundle has MIME types as keys and the content as values, such as
text/plain text or image/png data, which the format
description’s examples store as base64 multi-line text.
application/json, and from 4.2 any type ending +json
(backported to 4.0), hold JSON as it is, not serialised into a string. An output of
an unknown output_type is allowed with any keys.
Versions
| Version | Change |
|---|---|
| 4.0 | The version-3 worksheets array gives way to a top-level cells array (from comparing the two schemas). Heading cells removed (Markdown headings instead). input renamed source, prompt_number renamed execution_count, pyout renamed execute_result, pyerr renamed error, stream’s stream key renamed name; output data moved into data keyed by full MIME type. |
| 4.1 | Cell attachments. |
| 4.2 | +json MIME types hold raw JSON. |
| 4.3, 4.4 | Unknown: the format description does not say what these minor versions changed. |
| 4.5 | Required cell id. |
nbformat 3, from its schema: top-level metadata,
nbformat, nbformat_minor and worksheets (each
with cells and optional metadata), optionally
orig_nbformat and orig_nbformat_minor. Cell types:
code (input, language, outputs,
prompt_number, optional collapsed), markdown
(also "html"), raw and heading (with
level, 1 or more). Output types: pyout (with
prompt_number), display_data, stream (with a
stream key) and pyerr; data sat under short keys
text, latex, png, jpeg,
svg, html, javascript, json,
pdf.