{"id":540,"library":"nbformat","title":"Jupyter Notebook Format","description":"nbformat is the reference implementation of the Jupyter Notebook format, providing Python APIs for programmatically creating, reading, modifying, and validating Jupyter Notebook files (.ipynb). It is currently at version 5.10.4 and follows the Jupyter project's release cadence, with major versions aligning with significant changes to the notebook format specification.","status":"active","version":"5.10.4","language":"python","source_language":"en","source_url":"https://github.com/jupyter/nbformat","tags":["jupyter","notebook","ipynb","serialization","data science"],"install":[{"cmd":"pip install nbformat","lang":"bash","label":"Install nbformat"}],"dependencies":[{"reason":"Used for validating notebook structure against the schema.","package":"jsonschema","optional":false},{"reason":"Optional faster JSON schema validator, enabled via environment variable NBFORMAT_VALIDATOR.","package":"fastjsonschema","optional":true}],"imports":[{"symbol":"nbformat","correct":"import nbformat"},{"note":"`nbformat.current` is deprecated since before nbformat 3.0. Always import from specific version modules like `nbformat.v4` for composing new notebooks.","wrong":"from nbformat.current import new_notebook","symbol":"new_notebook","correct":"from nbformat.v4 import new_notebook"}],"quickstart":{"code":"import nbformat\nfrom nbformat.v4 import new_notebook, new_markdown_cell, new_code_cell\nimport os\n\n# 1. Create a new notebook\nnb = new_notebook()\n\n# Add a markdown cell\nnb.cells.append(new_markdown_cell(\"## My First Notebook (nbformat)\"))\n\n# Add a code cell\ncode_cell_content = \"print('Hello from nbformat!')\\nx = 1 + 2\\nprint(f'The sum is: {x}')\"\nnb.cells.append(new_code_cell(code_cell_content))\n\n# Define output path\nnotebook_filename = 'example_notebook.ipynb'\n\n# 2. Write the notebook to a file\nwith open(notebook_filename, 'w', encoding='utf-8') as f:\n    nbformat.write(nb, f)\nprint(f\"Notebook '{notebook_filename}' created successfully.\")\n\n# 3. Read an existing notebook\nread_nb = None\nif os.path.exists(notebook_filename):\n    with open(notebook_filename, 'r', encoding='utf-8') as f:\n        # Specify as_version=4 to ensure it's read as the V4 format\n        read_nb = nbformat.read(f, as_version=4)\n    print(f\"\\nNotebook '{notebook_filename}' read successfully.\")\n    print(f\"Notebook format version: {read_nb.nbformat}.{read_nb.nbformat_minor}\")\n    for i, cell in enumerate(read_nb.cells):\n        print(f\"\\n--- Cell {i+1} ({cell.cell_type}) ---\")\n        print(cell.source)\nelse:\n    print(f\"Error: '{notebook_filename}' not found for reading.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to Python 3.8 or newer.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"The `nbformat.current` module is deprecated. It was intended for backward compatibility but can lead to confusion regarding notebook versions.","severity":"deprecated","affected_versions":"All versions >=3.0 (deprecated before 3.0)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:49:29.371Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure `nbformat` is installed in the correct environment by running: `pip install nbformat` or `conda install nbformat`. If using an IDE like VS Code, verify the selected Python interpreter matches the environment where `nbformat` was installed.","cause":"The `nbformat` package is not installed in the currently active Python environment, or the environment where it is installed is not the one being used by the application (e.g., VS Code, Jupyter).","error":"ModuleNotFoundError: No module named 'nbformat'"},{"fix":"Upgrade `nbformat` to the latest version: `pip install --upgrade nbformat`. After upgrading, it is often necessary to restart the kernel or the entire Jupyter/VS Code session.","cause":"This error typically occurs when a library (e.g., Plotly) attempts to render rich output in a Jupyter Notebook, but the installed version of `nbformat` is older than the required minimum version (e.g., 4.2.0) or is not correctly detected.","error":"ValueError: Mime type rendering requires nbformat>=4.2.0 but it is not installed"},{"fix":"Use the `nbformat.validator.normalize()` function to add missing ID fields and normalize the notebook structure. For example: `import nbformat; from nbformat import validator; with open('problematic.ipynb', 'r') as f: nb_corrupted = nbformat.read(f, as_version=4); nb_fixed = validator.normalize(nb_corrupted); with open('fixed.ipynb', 'w') as f_out: nbformat.write(nb_fixed, f_out)`. Newer versions of nbformat (>=5.1.4) provide this `normalize` method.","cause":"This warning indicates that one or more cells in a Jupyter notebook are missing a unique 'id' field, which became mandatory in `nbformat` 4.5. This often happens with older notebooks, or when cells are copied and pasted, leading to an incomplete notebook structure.","error":"MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions."},{"fix":"Ensure the notebook file is well-formed JSON. If the issue is due to a version mismatch, explicitly specify the `as_version` parameter when reading (`nbformat.read(fp, as_version=4)`), or ensure the notebook's internal `nbformat` and `nbformat_minor` metadata fields correctly reflect its structure. For deep corruption, manual inspection and correction of the `.ipynb` file as plain text might be necessary, or attempting to convert it with a compatible `nbconvert` version.","cause":"A `ValidationError` (or `NBFormatError` in older versions) indicates that the notebook file does not conform to the expected Jupyter Notebook format specification, meaning its JSON structure is invalid. This can be due to file corruption, manual edits that introduce errors, or attempting to read/write a notebook with an incompatible `nbformat` version or schema.","error":"nbformat.ValidationError: ('Notebook failed to convert.',) or NBFormatError"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.44,"mem_mb":9.2,"disk_size":"23.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.29,"mem_mb":9.2,"disk_size":"24M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.64,"mem_mb":9.4,"disk_size":"26.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.61,"mem_mb":9.4,"disk_size":"26M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.6,"mem_mb":9.1,"disk_size":"17.9M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.56,"mem_mb":9.1,"disk_size":"18M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.41,"mem_mb":8.8,"disk_size":"17.1M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.36,"mem_mb":8.8,"disk_size":"17M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.5,"mem_mb":10.1,"disk_size":"23.1M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.52,"mem_mb":10.1,"disk_size":"23M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}