Embedding Jupyter Notebook Cells
This feature is new in Quarto 1.3, which you can download at https://quarto.org/docs/download/
Overview
You can include the output of an external Jupyter notebook in a Quarto document with the embed
shortcode. To embed a notebook cell, provide the path to a Jupyter Notebook and a cell identifier. For example, this notebook called penguins.ipynb
has a cell labelled fig-bill-scatter
:

You can use the following shortcode to embed the output of this cell:
{{< embed penguins.ipynb#fig-bill-scatter >}}
This will embed the plot as follows:
A link to the source notebook is automatically provided beneath the plot. Following the link takes users to a rendered version of the notebook, allowing them to explore the notebook without having to download and run it locally. For example, clicking on the link to penguins.ipynb
gets you to a page that looks like the following:

Beyond this basic usage, you can also:
Specify cells in multiple ways, see Specifying Cells.
Control the output using code cell options in the source Notebook, including things like figure captions, figure layout, and code display, see Code Cell Options.
Include the cell code along with the output by adding an
echo
option to the shortcode, see Embedding Code.Customize or exclude the link to the the source notebooks, see Links to Source Notebooks.
Specifying Cells
The embed
shortcode specifies target notebooks using a relative path followed by a cell identifier (e.g. penguins.ipynb#fig-bill-scatter
). If the cell identifier is omitted, all of the cells in the notebook will be embedded in the document.
The cell identifier is used to locate the proper cell using the following heuristics:
- Cell
id
First, the cell metadata will be checked for a matchingid
. (Cell IDs are a newer feature of Jupyter Notebooks that are not yet well supported in Jupyter front ends, butid
is checked first to allow for future compatibility as they become more common). - Label
If no cell with a matchingid
is found, Quarto will use a cell that has alabel
in the code metadata which matches the cell identifier. - Tags
If no cell has been found, Quarto will use a cell or cell(s) whose tag matches the cell identifier.
Code Cell Options
Code cell options from the source Jupyter Notebook are propagated to the document in which they are embedded. For instance, you may specify code cell options like fig-cap
, fig-alt
and layout-ncol
, to control aspects of embedded figures. For example, this cell in the Notebook specifies figure options including a caption, sub-caption, alt text and layout:
penguins.ipynb
#| label: fig-bill-marginal
#| fig-cap: "Marginal distributions of bill dimensions"
#| fig-subcap:
#| - "Gentoo penguins tend to have thinner bills,"
#| - "and Adelie penguins tend to have shorter bills."
#| fig-alt:
#| - "Density plot of bill depth by species."
#| - "Density plot of bill length by species."
#| layout-ncol: 2
sns.displot(penguins, = "bill_depth_mm",
x = "species",
hue = "kde", fill = True, aspect = 2, height = 3)
kind
plt.show()
sns.displot(penguins, = "bill_length_mm",
x = "species",
hue = "kde", fill = True, aspect = 2, height = 3)
kind plt.show()
When this cell is embedded:
{{< embed penguins.ipynb#fig-bill-marginal >}}
The following output is produced:
Embedding Code
You may include the code from a cell along with the output by using the echo=true
option. For example, to include the code and the plot from the cell labelled species-counts
the embed would be:
{{< embed penguins.ipynb#species-counts echo=true >}}
The result in the document is both the code and output for the cell:
Like figure options, options for displaying the code will propagate from the source Jupyter Notebook. For example, to fold the code for this cell, you could add code-fold: true
to the options for the species-counts
cell:
penguins.ipynb
#| label: species-counts
#| code-fold: true
"species").size().reset_index(name = "count") penguins.groupby(
The options set in the YAML header for the document in which these cells are embedded will also control these code cells. For example, to fold all the code, including the code embedded from penguins.ipynb
, you could add code-fold: true
to the document YAML:
sample.qmd
title: Exploration of penguin characteristics
author: Norah Jones
toc: true
format:
html:
code-fold: true
Links to Source Notebooks
When you embed the contents of Notebooks in a Quarto document and render the document to HTML, Quarto will automatically include links to the source Notebooks that provided the embedded content. These links will by default appear both inline below the embedded content as well as below the table of contents. For example, the following document embeds content from the notebook penguins.ipynb
. You can see the links in the rendered HTML document below:

Link Placement
You can control the placement of the links to source notebooks by specifying the option notebook-links
in the document YAML with one of the following values:
true
(default)-
Display links to source notebooks inline below the embedded content, and alongside the table of contents.
false
-
Do not display any links to source notebooks.
inline
-
Display only the links inline below the embedded content.
global
-
Display only the links alongside the table of contents.
Notebook Views
By default, the link to the source notebook goes to an automatically generated HTML render of the notebook. This makes it easier for users to view the Notebook contents without needing to download and run the Notebook locally. This notebook view displays the contents of the notebook and includes a button to download the notebook. For example:

As an example, you can view the live preview for the `penguins.ipynb` notebook used in this document.
View Options
You can control the behavior of notebook views using notebook-view
. For each source notebook, you can provide a title
and a url
. The title
will be used as the text of the any links to the source notebook and will also appear at the top of the rendered notebook view. The url
, if provided, will be used as the href
of any links to the source notebook. This is useful if you have deployed a copy of the source notebook to a site like Github, Google Colab, or Kaggle and would rather link to that instead.
For example:
notebook-view:
- notebook: penguins.ipynb
title: "Plots and Computations" url: https://colab.research.google.com/drive/12GsIPQ644SI4vkEEHiZn-Qqfbr-bD1__
will result in links to the source notebook like so:

To disable the notebook views, and instead link directly to the Jupyter notebook (so the user may download the notebook with no intermediary view), set notebook-view
to false
.