Execution Options

Introduction

This guide provides an overview of code execution options in Quarto, a versatile computational document system. Quarto supports multiple engines, including Jupyter and Knitr, and offers a range of options for customizing code outputs in your documents.

This guide covers the following topics:

Code output options: Learn how to customize and control code outputs in your Quarto documents.
Diverse formats: Tailor execution settings for various document formats, including HTML, PDF, and slides.
Advanced customizations: Figure sizing and error handling for enhanced document presentation.
Tool compatibility: Ideal for users employing Jupyter or Knitr tools, ensuring functionality across different computational platforms.

Output Options

Hide code from the output document using echo: false in the document yaml settings:

---
title: "My Document"
execute:
  echo: false
jupyter: python3
---

Override this option on a per code-block basis:

```{python}
#| echo: true

import matplotlib.pyplot as plt
plt.plot([1,2,3,4])
plt.show()
```

Note

Code block options are included in a special comment at the top of the block. Lines at the top prefaced with #| are considered options.

Options for customizing output:

Output Option	Description
`eval`	Evaluate the code chunk (if `false`, just echos the code into the output).
`echo`	Include the source code in output.
`output`	Include the results of executing the code in the output (`true`, `false`, or `asis` to indicate that the output is raw markdown and should not have any of Quarto’s standard enclosing markdown).
`warning`	Include warnings in the output.
`error`	Include errors in the output (note that this implies that errors executing code will not halt processing of the document).
`include`	Catch all for preventing any output (code or results) from being included (e.g. `include: false` suppresses all output from the code block).

Knitr example with some of these additional options included:

---
title: "Knitr Document"
execute:
  echo: false
---

```{r}
#| warning: false

library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess", se = FALSE)
```

```{r}
summary(airquality)
```

Tip

When using the Knitr engine, you can also use any of the available native options (e.g. collapse, tidy, comment, etc.). See the Knitr options documentation for additional details. You can include these native options in option comment blocks as shown above, or on the same line as the {r} as shown in the Knitr documentation.

Figure Options

Defaults figure width and height (expressed in inches per document type):

Document Format	Default Value
Default	7 x 5
HTML Slides	9.5 x 6.5
HTML Slides (reveal.js)	9 x 5
PDF	5.5 x 3.5
PDF Slides (Beamer)	10 x 7
PowerPoint	7.5 x 5.5
MS Word, ODT, RTF	5 x 4
EPUB	5 x 4
Hugo	8 x 5

Change the default sizes using the fig-width and fig-height options:

---
title: "My Document"
format: 
  html:
    fig-width: 8
    fig-height: 6
  pdf:
    fig-width: 7
    fig-height: 5
---

Caution

When using the Knitr engine, fig-width and fig-height are supported on a per-cell basis. But when using the Jupyter engine, these options only have an effect if specified at the document- or project-level metadata.

Caption and Alt Text

Use fig-cap and fig-alt options for captions and alt text in code-generated figures.
Example in a R plot code cell:

```{r}
#| fig-cap: "Scatter Plot"
#| fig-alt: "A scatter plot from R"

plot(1:10)
```

Raw Output

Use output: asis for raw markdown output without Quarto’s standard divs.
Example: generate headings with output: asis.

Jupyter
Knitr

```{python}
#| echo: false
#| output: asis

print("# Heading 1\n")
print("## Heading 2\n")
```

```{r}
#| echo: false
#| output: asis

cat("# Heading 1\n")
cat("## Heading 2\n")
```

Output:

# Heading 1

## Heading 2

Tip

Note that we also include the echo: false option to ensure that the code used to generate markdown isn’t included in the final output.

For the Jupyter engine, you can also create raw markdown output using the functions in IPython.display:

```{python}
#| echo: false
radius = 10
from IPython.display import Markdown
Markdown(f"The _radius_ of the circle is **{radius}**.")
```

Knitr Options

If you are using the Knitr cell execution engine, you can specify default document-level Knitr chunk options in YAML. For example:

---
title: "My Document"
format: html
knitr:
  opts_chunk: 
    collapse: true
    comment: "#>" 
    R.options:
      knitr.graphics.auto_pdf: true
---

You can additionally specify global Knitr options using opts_knit.

The R.options chunk option is a convenient way to define R options that are set temporarily via options() before the code chunk execution, and immediately restored afterwards.

In the example above, we establish default Knitr chunk options for a single document. You can also add shared knitr options to a project-wide _quarto.yml file or a project-directory scoped _metadata.yml file.

Intermediates

Keep intermediate files during rendering with these options:

Rendering Option	Description
`keep-md`	Keep the markdown file generated by executing code.
`keep-ipynb`	Keep the notebook file generated from executing code (applicable only to markdown input files)

For example, here we specify that we want to keep the jupyter intermediate file after rendering:

---
title: "My Document"
execute:
  keep-ipynb: true
jupyter: python3
---

Fenced Echo

Use echo: fenced to display code delimiters (e.g., ```{python}) in tutorials or documentation.
Example:

```{python}
#| echo: fenced
1 + 1
```

Output:

```{python}
1 + 1
```

Useful for demonstrating cell options like output and code-overflow:

Example:

```{python}
#| echo: fenced
#| output: false
#| code-overflow: wrap
1 + 1
```

Output:

```{python}
#| output: false
#| code-overflow: wrap
1 + 1
```

This behavior can also be specified at the document level if you want all of your executable code blocks to include the fenced delimiter and YAML options:

---
title: "My Document"
format: html
execute:
  echo: fenced
---

Unexecuted Blocks

For unexecuted code blocks, use double curly braces around the language (e.g., {python}):

Example:

```{{python}}
1 + 1
```

Output:

```{python}
1 + 1
```

If you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````) and use the two curly brace syntax for code blocks within. For example:

---
title: "My document"
---

Some markdown content.

```{{python}}
1 + 1
```

Some additional markdown content.

Shell Commands

Usage of shell commands (from Bash, Zsh, etc.) within Quarto computational documents differs by engine.

Jupyter
Knitr

Using Jupyter shell magics:

---
title: "Using Bash"
engine: jupyter
---

```{python}
!echo "foo"
```

Note that ! preceding echo is what enables a Python cell to be able to execute a shell command.

Using ```{bash} cells:

---
title: "Using Bash"
engine: knitr
---

```{bash}
echo "foo" 
```

Note

The Knitr engine also supports ```{python} cells, enabling the combination of R, Python, and Bash in the same document

References

Quarto Execution Options