Checking a project with –dry-run
q2 render --dry-run checks a document or a whole project without
rendering it. It finds the project and its files, works out each file’s
format, then parses every file and merges its metadata with the
project’s. It reports every problem it finds and exits. It executes no
code, runs no pre- or post-render script, and writes
nothing, not even to .quarto/.
It is meant for places where a full render is too slow, or not possible: a CI job or a pre-commit hook that should fail fast on a broken file, or an agent checking its edits.
q2 render --dry-run # the whole project
q2 render chapter.qmd --dry-run # one file (and its project, if any)
q2 render --dry-run --strict # warnings fail the check tooWhat it checks, and what it does not
A dry run reports:
- every parse error, in every file (the run does not stop at the first
one unless you pass
--fail-fast); - warnings from the front matter and the metadata merge, such as a
css:entry naming a missing file; - problems with the project itself:
project.renderpatterns that match nothing, a book chapter list that names a missing file, a format a book cannot be rendered to.
It does not report problems that only a full render can find, because it stops before running any code or transforming any document:
- errors from code cells and their engines (Jupyter, knitr, …);
- Lua filter errors;
- unresolved cross-references, links and citations;
- template errors, and warnings about the rendered content, such as a
[text]with no link target.
A clean dry run means every file parses and the project holds together. It does not guarantee that the render will succeed.
The project’s pre-render scripts do not run. If a script creates input
files, those files are only checked when they already exist.
Reading the result
The exit status is the same as a render’s: non-zero when there are
errors, and with --strict, when there are warnings too. The last line
summarises the run:
Checked 42 files — 2 errors, 3 warnings
Add -v to also list the files a render would produce, each with its
format. Files that failed to parse are marked as skipped:
Would render 3 files:
index.qmd (html)
slides.qmd (revealjs)
broken.qmd (html) — would be skipped: failed to parse
Machine-readable output
With --json-errors, every diagnostic goes to stderr as one JSON object
per line, in the same form a real render uses. After the run, stdout
holds exactly one JSON object summarising the check:
{"$schema":"https://quarto.org/schemas/v1/render-dry-run-summary.json",
"dry_run":true,"project_dir":"/work/site","format":"html",
"files_checked":42,"files_failed":1,"errors":2,"warnings":3,
"strict":false,"stopped_early":false}(Shown wrapped here. It is printed as a single line.)
errorsandwarningscount the diagnostics on stderr, after--stricthas turned warnings into errors.stopped_earlyistruewhen--fail-faststopped the run at the first failure, in which case not every file was checked.- With
-v, afilesarray lists the files a render would produce, as{"source_file": …, "format": …, "status": "ok" | "failed"}. Without-vthe key is absent. - With
--json-errors,-vdoes not add log lines to stderr, so stderr stays pure JSON.
The summary’s JSON Schema is in the q2 repository at
crates/quarto/schemas/render-dry-run-summary.json.
Options it ignores
Because nothing executes and nothing is written, options about
execution and output, such as --execute-*, --cache, -o and
--output-dir, are accepted and have no effect. --clean-cache cannot
be combined with --dry-run, which never modifies the cache.
--to, -M, --profile and the input paths work as they do for a
render, since they change what is checked.