← All guides

What is an .ipynb file?

An .ipynb file is a Jupyter Notebook: a single document that stores code, formatted text, and the outputs of running that code (tables, charts, printed results) together in one file. The extension stands for Interactive Python Notebook, though notebooks can run languages other than Python. Under the hood it is not a special binary format, it is a plain-text JSON file following the official nbformat schema, which is why the same notebook can be opened in Jupyter, VS Code, Google Colab, or Kaggle, and converted to other formats like PDF, HTML, or a .py script. If you have one and just need a readable, shareable version, you can convert it to PDF in your browser without installing anything.

What's actually inside an .ipynb file

Open an .ipynb in a text editor and you will see JSON. At the top level it is a dictionary with four keys:

{
  "cells": [ ... ],
  "metadata": { ... },
  "nbformat": 4,
  "nbformat_minor": 5
}
  • cells is an ordered list, the heart of the notebook. Each cell is one of three types:
    • code cells: source code, plus any saved outputs from running it, and an execution_count.
    • markdown cells: formatted narrative text (headings, lists, links, math).
    • raw cells: content passed through untouched by converters.
  • metadata records things like the kernel and language (e.g. Python 3) the notebook was written for.
  • nbformat / nbformat_minor are the format version. Version 4 is the current major version.

The key insight: a notebook stores both the inputs (your code and text) and the saved outputs (results, tables, images) in the same file. Images and charts are typically embedded as base64-encoded data right in the JSON, which is why a notebook with many plots can get large.

Why it's JSON (and why you shouldn't hand-edit it)

Storing notebooks as JSON is what makes them portable and tool-agnostic: any program that can read the nbformat schema can open, render, or transform the notebook. It also means a notebook is technically human-readable.

That said, editing the JSON by hand is risky. It is easy to corrupt the structure (a stray comma, a broken output block) and make the file unopenable. If you need to manipulate a notebook programmatically, use the official nbformat Python library rather than editing the raw text, the internal JSON details can change, but the library API is stable.

How to open an .ipynb file

You do not need to install anything heavy just to view one. Options, roughly easiest first:

  • Google Colab: upload and open in the browser, nothing to install.
  • VS Code: with the Jupyter extension, opens .ipynb files natively.
  • JupyterLab / Jupyter Notebook: the classic local environment (pip install notebook).
  • GitHub: renders .ipynb files automatically when you view them in a repo.
  • A viewer or converter: to just read or share it, converting to PDF or HTML avoids needing a notebook environment at all.

.ipynb vs .py: what's the difference?

A common point of confusion. A .py file is a plain Python script, just source code, run with python script.py. An .ipynb file is a notebook document: it bundles code and markdown explanations and saved outputs (charts, tables) in a cell structure. Notebooks are built for interactive, exploratory work, teaching, and reports; .py scripts are better for production code, version control (cleaner diffs), and automation. Converting a notebook to .py extracts just the code and drops the outputs.

Converting an .ipynb file

Because it is structured data, a notebook converts cleanly to several formats depending on your reader:

  • PDF, for a fixed, shareable report or a homework/assignment submission, or archiving. Convert .ipynb to PDF in your browser, no LaTeX or install required, and the notebook stays on your device.
  • HTML, for a browser-readable version you can publish.
  • .py, when you only need the source code.

For the PDF route specifically, the traditional nbconvert --to pdf path requires a LaTeX install and often fails with a xelatex not found error; see how to save a notebook as PDF for the no-LaTeX options, and convert a notebook to PDF without LaTeX for the method comparison.

Quick facts

  • Extension: .ipynb (Interactive Python Notebook)
  • Format: plain-text JSON, per the nbformat schema
  • Contains: code cells, markdown cells, saved outputs, metadata
  • Opens in: Jupyter, JupyterLab, VS Code, Colab, Kaggle, GitHub
  • Converts to: PDF, HTML, .py, Markdown, and more

References