gohugoio/hugo · error

rst2html / rst2html.py not found in $PATH, cannot render %q

Error message

rst2html / rst2html.py not found in $PATH, cannot render %q

What it means

Hugo renders reStructuredText content by shelling out to Docutils' `rst2html` (or `rst2html.py`) script. `getRstContent` resolves the binary name and path first; if neither name is found on $PATH, the .rst page cannot be rendered and the build fails, naming the document.

Source

Thrown at markup/rst/convert.go:70

	b, err := c.getRstContent(ctx.Src, c.ctx)
	if err != nil {
		return nil, err
	}
	return converter.Bytes(b), nil
}

func (c *rstConverter) Supports(feature identity.Identity) bool {
	return false
}

// getRstContent calls the Python script rst2html as an external helper
// to convert reStructuredText content to HTML.
func (c *rstConverter) getRstContent(src []byte, ctx converter.DocumentContext) ([]byte, error) {
	logger := c.cfg.Logger
	binaryName, binaryPath := getRstBinaryNameAndPath()

	if binaryName == "" {
		return nil, fmt.Errorf("rst2html / rst2html.py not found in $PATH, cannot render %q", ctx.DocumentName)
	}

	logger.Infoln("Rendering", ctx.DocumentName, "with", binaryName, "...")

	args := []string{"--leave-comments", "--initial-header-level=2"}
	if c.cfg.Conf != nil && c.cfg.MarkupConfig().RST.SyntaxHighlight != "long" {
		args = append(args, "--syntax-highlight="+c.cfg.MarkupConfig().RST.SyntaxHighlight)
	}

	var result []byte
	var err error

	// certain *nix based OSs wrap executables in scripted launchers
	// invoking binaries on these OSs via python interpreter causes SyntaxError
	// invoke directly so that shebangs work as expected
	// handle Windows manually because it doesn't do shebangs
	if runtime.GOOS == "windows" {
		pythonBinary, _ := internal.GetPythonBinaryAndExecPath()

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Install Docutils (`pip install docutils`) and ensure its scripts directory (e.g. ~/.local/bin) is on $PATH for the Hugo process.
2. In CI, add a docutils install step before the Hugo build.
3. Verify with `which rst2html rst2html.py` in the same shell that runs Hugo.
4. If RST support isn't needed, convert the content to Markdown; also ensure Hugo's `security.exec.allow` permits rst2html.

Example fix

# before (CI)
hugo
# after (CI)
pip install docutils
export PATH="$HOME/.local/bin:$PATH"
hugo

if _, err := exec.LookPath("rst2html"); err != nil {
    if _, err2 := exec.LookPath("rst2html.py"); err2 != nil {
        return fmt.Errorf("docutils (rst2html) required for .rst content but not installed")
    }
}

When it happens

Trigger: Building a site containing `.rst` content files (or `markup: rst` front matter) on a machine where neither `rst2html` nor `rst2html.py` is on $PATH — Docutils not installed, or installed into a Python user/site directory whose scripts folder isn't exported.

Common situations: CI environments and Docker images without Python/Docutils; `pip install docutils` placing scripts in `~/.local/bin` which isn't on PATH; newer Docutils versions where the script naming changed on some distros; running `hugo server` before installing Docutils.

Related errors

• pandoc not found in $PATH, cannot render %q
• no Dart Sass binary found in $PATH
• asciidoctor not found in $PATH, cannot render %q
• failed to resolve output path %q: %w
• abort: jekyll root contains neither posts nor drafts

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/f5e2508e2d18d250.json. Report an issue: GitHub ↗.