Getting Started with Quarto

Overview

Quarto is an open-source scientific and technical publishing system. It lets you write text in Markdown, embed and run code (Julia, Python, R, or Observable JS), and render the combined document to HTML, PDF, Word, slides, and more, all from a single source file. If you have used Jupyter notebooks, think of Quarto as a way to get the same “code + narrative + output” workflow, but with much more control over the final, polished document — this is especially useful for writing up homework and project reports.

This entire course website, along with the lecture notes, was written in Quarto. You can (and are encouraged to!) use Quarto to write your homework solutions and project reports.

This tutorial covers:

  • installing Quarto and setting it up to run Julia code,
  • the basics of writing and rendering a .qmd file,
  • generating a PDF from a Quarto document, and
  • using Quarto inside VS Code.

Quarto has excellent official documentation. This tutorial is meant to get you up and running quickly for this course; for anything more advanced, the Quarto Guide is the best reference.

Installing Quarto

Quarto is a standalone command-line tool (it does not require Python, R, or Julia to install, though it can use any of them to run code). Download and install it from the official Get Started page:

  • Windows: Download and run the .exe installer from quarto.org/docs/download.

  • macOS: Download and run the .pkg installer from the same page, or install with Homebrew:

    brew install --cask quarto

Verify your installation

Open a new terminal window (so it picks up the updated PATH) and run:

quarto --version

You should see a version number (e.g., 1.6.40). It’s also worth running Quarto’s built-in diagnostic tool, which checks that your Quarto installation, LaTeX, and any notebook engines are configured correctly:

quarto check

This will print a report and flag anything that’s missing. Don’t worry if it says LaTeX is not installed — we’ll cover that below in Rendering to PDF.

Setting Up Quarto with Julia

Quarto needs to know how to execute the code in your document. This is handled by a notebook engine. As of Quarto 1.4+, there is a native Julia engine that Quarto manages for you automatically — you do not need to separately install Jupyter or IJulia. See the Quarto + Julia documentation for full details.

To use it, add engine: julia to the YAML header of your .qmd file, as at the top of this page (or any of the .qmd files provided in your homework repositories):

---
title: "My Document"
engine: julia
---

The first time you render a document with engine: julia, Quarto will automatically download and set up a small companion package called QuartoNotebookRunner.jl in its own isolated environment. This can take a minute or two — subsequent renders will be much faster, since Quarto keeps a background Julia process “warm” between renders of the same document.

Pinning a Julia version: If you use Juliaup to manage multiple Julia versions (as recommended on the Julia setup page), you can force Quarto to use a specific one with the exeflags option, as this page’s own YAML header does:

julia:
    exeflags: ["+1.11.5"]

Your .qmd file should also live alongside a Project.toml (and, after your first run, a Manifest.toml) that lists the packages it needs — exactly as you would set up a Julia environment for a script or notebook. See Julia Environments and Packages for a refresher on Pkg.activate and Pkg.instantiate.

Alternative: the Jupyter engine. If you’d rather use Jupyter + IJulia (e.g., because you’re already comfortable with that setup from Python), Quarto supports that too via engine: jupyter. See the Jupyter section of the Julia engine docs for how to register a Julia kernel.

Anatomy of a Quarto Document

A .qmd file has three parts:

  1. A YAML header, delimited by --- lines, containing metadata (title, author, output format, engine, etc.).
  2. Markdown text — the same syntax used in the rest of this website (see the Markdown resources page for a refresher).
  3. Code chunks, fenced with three backticks and a curly-brace language tag, e.g. ```{julia}.

Here’s a minimal example:

---
title: "My First Quarto Document"
engine: julia
---

## Introduction

This document computes the growth of a pollutant stock over time.

```{julia}
using Plots

t = 0:0.1:10
C = 5 .* exp.(-0.3 .* t)
plot(t, C, xlabel="Time", ylabel="Concentration", legend=false)
```

The concentration decays exponentially, as shown above.

Code chunk options

You can control how a chunk behaves with #| comment options at the top of the chunk. Common ones:

Option Effect
#\| echo: false Hide the code, show only the output
#\| eval: false Show the code but don’t run it
#\| output: false Run the code but hide the output
#\| warning: false Suppress warnings
#\| fig-cap: "..." Add a caption to a figure
#\| label: fig-mylabel Add a cross-reference label (use with @fig-mylabel in text)

For example, this chunk uses echo: false to show only the resulting figure:

Example figure generated from a hidden code chunk.

The full list of chunk options is in the Quarto code cells reference.

Math and citations

Math works the same as in a Jupyter notebook — enclose LaTeX in $...$ for inline math or $$...$$ for display math. See the Using LaTeX in Jupyter Notebooks tutorial for a full guide to LaTeX syntax (it applies equally to Quarto).

Citations use a .bib file referenced in the YAML header and [@key] syntax in the text; see the Quarto citations guide if your report needs references.

Rendering a Document

To render a .qmd file from the command line:

quarto render mydocument.qmd

This produces output in whatever format is listed under format: in the YAML header (HTML by default if nothing is specified). You can preview your document with live reload as you edit it:

quarto preview mydocument.qmd

This opens your document in a browser tab that automatically refreshes as you save changes.

Rendering to PDF

To generate a PDF, either set format: pdf in the YAML header, or pass --to pdf on the command line without changing the header:

quarto render mydocument.qmd --to pdf

Quarto’s default PDF engine uses LaTeX. If you don’t already have a LaTeX distribution installed, Quarto can install a lightweight one called TinyTeX (~250 MB) for you:

quarto install tinytex

This course’s Converting Jupyter Notebooks to PDF tutorial covers PDF rendering with Quarto in more depth, including using Typst (quarto install typst, then quarto render mydocument.qmd --to typst) as a much lighter, faster, LaTeX-free alternative for producing PDFs. Everything there applies whether your .qmd started life as a notebook or as a Quarto document from the start.

For full control over PDF appearance (margins, fonts, table of contents, etc.), see the PDF format reference and the Typst format reference.

Quarto in VS Code

VS Code has first-class support for Quarto through an official extension, and it works alongside the Julia extension you should already have installed.

Install the extension

  1. Open the Extensions view (Ctrl/Cmd + Shift + X).
  2. Search for quarto and install the extension named Quarto (published by quarto), or install it directly from the VS Code Marketplace.
  3. Restart VS Code.

The extension detects your Quarto installation automatically. If it can’t find it, open VS Code Settings (Ctrl/Cmd + ,), search for quarto.path, and point it to your quarto executable (run which quarto in a terminal to find it).

Using the extension

Once installed, open any .qmd file:

  • A Render button appears above the YAML header (and in the editor title bar). Click it, or use the keyboard shortcut Ctrl/Cmd + Shift + K, to render and preview the document in a side-by-side pane.
  • Code chunks get the same run cell affordances as a Jupyter notebook — click the ▷ icon to the left of a chunk, or place your cursor inside it and press Ctrl/Cmd + Enter, to run just that chunk in an interactive Julia session.
  • The Visual Editor (toggle in the top-right of the editor, or Ctrl/Cmd + Shift + F4) gives you a WYSIWYG-style view for writing prose, useful if you find raw Markdown source distracting.
  • YAML header fields get autocompletion and inline documentation as you type.

Rendering a .qmd with engine: julia from VS Code uses the same Julia installation as the Julia extension. If code chunks fail to run, double check julia.executablePath as described in the VS Code setup tutorial.

For a full walkthrough with screenshots, see Quarto’s own VS Code guide.

Troubleshooting

quarto: command not found: Open a new terminal window — installers update your PATH, but existing terminal sessions won’t see the change. If it still fails, confirm the install location is on your PATH (run quarto check from the Quarto installer’s directory, or reinstall).

Rendering a Julia chunk hangs or is very slow the first time: This is expected — Quarto is downloading and precompiling QuartoNotebookRunner.jl and your project’s packages. Let it finish; subsequent renders reuse the warm session and are much faster.

“LaTeX Error” or “pdflatex not found” when rendering to PDF: You need a LaTeX distribution. Run quarto install tinytex, then try again. See the LaTeX troubleshooting section of the notebook-to-PDF tutorial for PATH-related issues.

Wrong Julia version is used: Check the julia.exeflags setting in your YAML header (or lack thereof) against juliaup status. If you don’t pin a version with exeflags, Quarto uses your Juliaup default.

Package errors when rendering: Just like a script or notebook, delete the Manifest.toml in your document’s folder and re-run a chunk containing Pkg.activate(@__DIR__); Pkg.instantiate() (see Julia Environments and Packages).

VS Code doesn’t show a Render button: Confirm the Quarto extension is installed and enabled, and that the file is saved with a .qmd extension (not .md or .ipynb).

Further Resources