{"record":{"id":"f5e2508e2d18d250","repo":"gohugoio/hugo","slug":"rst2html-rst2html-py-not-found-in-path-cannot","errorCode":null,"errorMessage":"rst2html / rst2html.py not found in $PATH, cannot render %q","messagePattern":"rst2html / rst2html\\.py not found in \\$PATH, cannot render %q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"markup/rst/convert.go","lineNumber":70,"sourceCode":"\tb, err := c.getRstContent(ctx.Src, c.ctx)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn converter.Bytes(b), nil\n}\n\nfunc (c *rstConverter) Supports(feature identity.Identity) bool {\n\treturn false\n}\n\n// getRstContent calls the Python script rst2html as an external helper\n// to convert reStructuredText content to HTML.\nfunc (c *rstConverter) getRstContent(src []byte, ctx converter.DocumentContext) ([]byte, error) {\n\tlogger := c.cfg.Logger\n\tbinaryName, binaryPath := getRstBinaryNameAndPath()\n\n\tif binaryName == \"\" {\n\t\treturn nil, fmt.Errorf(\"rst2html / rst2html.py not found in $PATH, cannot render %q\", ctx.DocumentName)\n\t}\n\n\tlogger.Infoln(\"Rendering\", ctx.DocumentName, \"with\", binaryName, \"...\")\n\n\targs := []string{\"--leave-comments\", \"--initial-header-level=2\"}\n\tif c.cfg.Conf != nil && c.cfg.MarkupConfig().RST.SyntaxHighlight != \"long\" {\n\t\targs = append(args, \"--syntax-highlight=\"+c.cfg.MarkupConfig().RST.SyntaxHighlight)\n\t}\n\n\tvar result []byte\n\tvar err error\n\n\t// certain *nix based OSs wrap executables in scripted launchers\n\t// invoking binaries on these OSs via python interpreter causes SyntaxError\n\t// invoke directly so that shebangs work as expected\n\t// handle Windows manually because it doesn't do shebangs\n\tif runtime.GOOS == \"windows\" {\n\t\tpythonBinary, _ := internal.GetPythonBinaryAndExecPath()","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/markup/rst/convert.go#L52-L88","documentation":"Returned by the rst converter when getRstBinaryNameAndPath() finds neither 'rst2html' nor 'rst2html.py' in $PATH (checked via hexec.LookPath). Hugo invokes rst2html as an external Python tool to convert reStructuredText; without it, RST content cannot be rendered.","triggerScenarios":"Building any .rst content file on a host lacking both rst2html and rst2html.py. Fires from rstConverter.getRstContent -> Convert during content rendering.","commonSituations":"Python docutils not installed (`pip install docutils` provides rst2html); CI image without Python toolchain; a host where rst2html is installed but only under a virtualenv not active when Hugo runs; Windows machines where the binary needs the explicit .py suffix and the Python interpreter.","solutions":["Install docutils: `pip install docutils` (or `pip3 install docutils`), which provides rst2html/rst2html.py.","Confirm `which rst2html || which rst2html.py` (or `where` on Windows) succeeds in Hugo's environment.","On Debian/Ubuntu: `apt-get install -y python3-docutils`; on macOS: `brew install docutils`.","If RST is not needed, remove the .rst files or reconfigure the markup so rst is not selected."],"exampleFix":"# before: rst2html missing\npip install --no-input mkdocs   # docutils not pulled in\n\n# after\npip install docutils","handlingStrategy":"validation","validationCode":"// Check for rst2html before building RST content.\nimport \"os/exec\"\n\nfunc ensureRst2html() error {\n    for _, c := range []string{\"rst2html\", \"rst2html.py\"} {\n        if p, err := exec.LookPath(c); err == nil && p != \"\" {\n            return nil\n        }\n    }\n    return fmt.Errorf(\"rst2html not found; run: pip install docutils\")\n}","typeGuard":null,"tryCatchPattern":"if _, err := rstconv.Convert(rc); err != nil {\n    if strings.Contains(err.Error(), \"rst2html / rst2html.py not found\") {\n        // log install hint and continue without RST rendering\n    }\n}","preventionTips":["Install docutils in the same environment Hugo runs in.","CI: `pip install docutils` in the build step before `hugo`.","Prefer Markdown unless RST is required, to avoid the external dependency."],"tags":["rst","docutils","external-binary","path","python","rendering"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}