{"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/8a468df065a75c1c7cf9f6850f32148746590ea5/markup/rst/convert.go#L52-L88","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install Docutils (`pip install docutils`) and ensure its scripts directory (e.g. ~/.local/bin) is on $PATH for the Hugo process.","In CI, add a docutils install step before the Hugo build.","Verify with `which rst2html rst2html.py` in the same shell that runs Hugo.","If RST support isn't needed, convert the content to Markdown; also ensure Hugo's `security.exec.allow` permits rst2html."],"exampleFix":"# before (CI)\nhugo\n# after (CI)\npip install docutils\nexport PATH=\"$HOME/.local/bin:$PATH\"\nhugo","handlingStrategy":"validation","validationCode":"if _, err := exec.LookPath(\"rst2html\"); err != nil {\n    if _, err2 := exec.LookPath(\"rst2html.py\"); err2 != nil {\n        return fmt.Errorf(\"docutils (rst2html) required for .rst content but not installed\")\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install python docutils (`pip install docutils`) in all build environments before using .rst content","Verify with `rst2html --version` in CI setup steps","Whitelist rst2html in security.exec.allow","Consider converting .rst content to Markdown to drop the external dependency"],"tags":["hugo","rst","docutils","external-binary","path","environment"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}