Windows uv venv local quarto install has problems with backslashes --- patch included!

[reckoner]

I have:

• searched the issue tracker for similar issues
• installed the latest version of Quarto CLI
• formatted my issue following the Bug Reports guide

Bug description

diff --git a/share/filters/main.lua b/share/filters/main.lua
--- a/share/filters/main.lua
+++ b/share/filters/main.lua
@@ -3040,7 +3040,11 @@ function isInlineEl(el)
 end
 
 function compileTemplate(template, meta)
-  local f = io.open(pandoc.utils.stringify(template), "r")
+  template = pandoc.utils.stringify(template)
+  -- Pandoc treats the separator before `.venv` as an escape while parsing
+  -- the title-block attribute on Windows. Restore the resulting missing one.
+  template = template:gsub("([^/\\])%.venv", "%1/.venv")
+  local f = io.open(template, "r")
   if f then
     local contents = f:read("*all")
     f:close()

Steps to reproduce

You create a local uv venv .venv, then install quarto-cli using uv pip install quarto-cli and it won't work unless you use that patch.

Actual behavior

complains about lua code. The error is not informative.

Expected behavior

actually compile a document

Your environment

• windows 10, powershell 7

Quarto check output

Quarto 1.9.38
[>] Checking environment information...
      Quarto cache location: C:\Users\reckoner\AppData\Local\quarto
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.8.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.4.5: OK
      Typst version 0.14.2: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.9.38
      Path: D:\data_science\.venv\Lib\site-packages\quarto_cli\bin
      CodePage: 1252
[>] Checking tools....................OK
      TinyTeX: v2026.04
      Chromium: (not installed)
      Chrome Headless Shell: (not installed)
      VeraPDF: (not installed)
[>] Checking LaTeX....................OK
      Using: TinyTex
      Path: C:\Users\reckoner\AppData\Roaming\TinyTeX\bin\windows\
      Version: 2026
[>] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
      Source: Windows Registry
[>] Checking basic markdown render....OK
[>] Checking R installation...........(None)
      Unable to locate an installed version of R.
      Install R from https://cloud.r-project.org/
[>] Checking Python 3 installation....(None)
      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/
[>] Checking Julia installation...

[mcanouil]

@reckoner Thanks for the report, but it's incomplete.
Nothing from what you shared generates an error, you implied an error when rendering something, without actually showing so nor the exact context and error itself.

Also see Troubleshooting guide to enable debug and extended stack trace.
Finally, you've stated/checked "installed the latest version of Quarto CLI", but the latest is not 1.9.38 as reported by yourself. The latest is 1.10.18.

[reckoner]

project:
  type: book

book:
  title: "Systems"
  author: "reckoner"
  chapters:
    - index.qmd
    - chapter.qmd

format:
  pdf:
    pdf-engine: xelatex

Here is chapter.qmd

---
title: "Minimal Chapter"
---

Minimal chapter body.

Here is index.qmd

# Minimal Reproduction

This one-chapter book isolates Quarto's PDF title-block template compilation.

Quarto PDF title-block template reproduction

This is a minimal standalone Quarto book that reproduces the
following error from the parent project:

Error compiling template: .../share/projects/book/pandoc/title-block.md

It retains only two short chapters, PDF/XeLaTeX output, the book title metadata,
and the YAML title field in chapter.qmd. The latter is the minimal trigger:
replacing its YAML front matter with a Markdown heading makes the book render
successfully in this environment.

Run from this directory:

quarto render --to pdf

With Quarto 1.10.18, the expected result is the same title-block template
compilation error. No workaround or configuration change is included; this is
only a reproduction case.

[reckoner]

FATAL (C:/Users/reckoner/Documents/reckoner/.venv/Lib/site-packages/quarto_cli/share/filters/main.lua:3061) An error occurred:
Error compiling template: C:\Users\reckoner\Documents\best_practices_ai.venv\Lib\site-packages\quarto_cli\share\projects\book\pandoc\title-block.md
Error running filter 'C:/Users/reckoner/Documents/best_practices_ai/.venv/Lib/site-packages/quarto_cli/share/filters/main.lua':
...venv/Lib/site-packages/quarto_cli/share/filters/main.lua:4169: FATAL QUARTO ERROR
stack traceback:
        ...venv/Lib/site-packages/quarto_cli/share/filters/main.lua:2621: in function 'fatal'
        ...venv/Lib/site-packages/quarto_cli/share/filters/main.lua:2201: in function 'fail'
        ...venv/Lib/site-packages/quarto_cli/share/filters/main.lua:3061: in function 'compileTemplate'
        ...venv/Lib/site-packages/quarto_cli/share/filters/main.lua:4169: in local 'fn'
        ...o_cli\share\pandoc\datadir\..\..\filters\modules/jog.lua:34: in upvalue 'run_filter_function'
        ...o_cli\share\pandoc\datadir\..\..\filters\modules/jog.lua:226: in function <...o_cli\share\pandoc\datadir\..\..\filters\modules/jog.lua:205>
        (...tail calls...)
        [C]: in function 'pandoc.List.map'
        ...o_cli\share\pandoc\datadir\..\..\filters\modules/jog.lua:128: in upvalue 'recurse'
        ...o_cli\share\pandoc\datadir\..\..\filters\modules/jog.lua:225: in local 'jogger'
        ...o_cli\share\pandoc\datadir\..\..\filters\modules/jog.lua:174: in upvalue 'recurse'
        ...o_cli\share\pandoc\datadir\..\..\filters\modules/jog.lua:225: in function <...o_cli\share\pandoc\datadir\..\..\filters\modules/jog.lua:205>
        (...tail calls...)
        ...venv/Lib/site-packages/quarto_cli/share/filters/main.lua:575: in function <...venv/Lib/site-packages/quarto_cli/share/filters/main.lua:553>
        (...tail calls...)
        ...venv/Lib/site-packages/quarto_cli/share/filters/main.lua:1318: in local 'callback'
        ...venv/Lib/site-packages/quarto_cli/share/filters/main.lua:1336: in upvalue 'run_emulated_filter_chain'
        ...venv/Lib/site-packages/quarto_cli/share/filters/main.lua:1372: in function <...venv/Lib/site-packages/quarto_cli/share/filters/main.lua:1369>
WARN: Error encountered when rendering files

[mcanouil]

Thank you for the reproduction. The problem is confirmed, and the cause is not the same as the one in the proposed patch.

Root cause

The book renderer writes the path of title-block.md into a Pandoc attribute without an escape. Pandoc reads a backslash before a punctuation character as an escape and removes it. On Windows the separator before .venv is lost.

Investigation

For every chapter that has YAML front matter, the book renderer emits a .quarto-title-block code cell. The function resolveTitleBlockMarkdown puts the absolute path of title-block.md into a template attribute by string interpolation. The path gets no escape.

• quarto-cli/src/project/types/book/book-render.ts

  Lines 476 to 496 in abc6a78

  	const resolveTitleBlockMarkdown = (yaml?: Metadata) => {
  	if (yaml) {
  	const titleBlockPath = resourcePath(
  	"projects/book/pandoc/title-block.md",
  	);
  	const titleAttr = `template='${titleBlockPath}'`;
  	const frontMatter = `---\n${
  	stringify(yaml, { indent: 2 })
  	}\n---\n`;
  	const titleBlockMd = "```````{.quarto-title-block " +
  	titleAttr + "}\n" +
  	frontMatter +
  	"\n```````\n\n";
  	return titleBlockMd;
  	} else {
  	return "";
  	}
  	};

Pandoc then parses that attribute value. Inside a quoted attribute value, a backslash before a punctuation character is an escape, and Pandoc removes the backslash. A backslash before a letter is not an escape, and it stays. In a path such as C:\proj\.venv\Lib\title-block.md, the sequence \. becomes ., while \L and \U are not affected. This is why only the separator before .venv disappears, and it matches the path in your error message.

The behaviour is visible with Pandoc alone, with no Quarto involved. A code cell with this attribute, parsed with pandoc -f markdown -t native, returns a damaged value:

written by Quarto : template='C:\Users\me\proj\.venv\Lib\x.md'
parsed by Pandoc  : C:\Users\me\proj.venv\Lib\x.md

The Lua filter reads the attribute back from the parsed document. At that point the value is already damaged, so the filter has no way to recover the correct path.

• quarto-cli/src/resources/filters/quarto-post/book.lua

  Lines 43 to 60 in abc6a78

  	if el.attr.classes:includes('quarto-title-block') then
  	-- read the contents of the code cell
  	-- this should just be some metadata
  	local renderedDoc = pandoc.read(el.text, 'markdown')
  	-- render the title block using the metdata and
  	-- and the template
  	local template = el.attr.attributes['template']
  	-- process any author information
  	local processedMeta = authors.processAuthorMeta(renderedDoc.meta) or renderedDoc.meta
  	-- process license information for the book
  	processedMeta = license.processLicenseMeta(processedMeta)
  	-- read the title block template
  	local renderedBlocks = compileTemplate(template, processedMeta)

The filter passes the value to compileTemplate. The call to io.open fails because the file does not exist at the damaged path, and the filter raises the error that you report.

• quarto-cli/src/resources/filters/common/pandoc.lua

  Lines 164 to 186 in abc6a78

  	function compileTemplate(template, meta)
  	local f = io.open(pandoc.utils.stringify(template), "r")
  	if f then
  	local contents = f:read("*all")
  	f:close()
  	-- compile the title block template
  	local compiledTemplate = pandoc.template.compile(contents)
  	local template_opts = pandoc.WriterOptions {template = compiledTemplate}
  	-- render the current document and read it to generate an AST for the
  	-- title block
  	local metaDoc = pandoc.Pandoc(pandoc.Blocks({}), meta)
  	local rendered = pandoc.write(metaDoc, 'gfm', template_opts)
  	-- read the rendered document
  	local renderedDoc = pandoc.read(rendered, 'gfm')
  	return renderedDoc.blocks
  	else
  	-- luacov: disable
  	fail('Error compiling template: ' .. template)
  	-- luacov: enable
  	end

Two conditions are necessary. First, a chapter must have a YAML title, because that is what emits the .quarto-title-block cell. This explains your note that a Markdown heading in place of the front matter makes the book render. Second, the Quarto installation path must contain a directory that starts with a punctuation character. The directory .venv from uv venv .venv is exactly such a case.

The code is the same on main and on the v1.10 branch, so the problem is present in 1.10.18 as well.

One note on the patch in the first message. It corrects the symptom for the name .venv only. Every other directory that starts with a punctuation character stays broken, and a real directory such as a.venv becomes a/.venv. The correct place to act is where the attribute is written, not where the path is read.