sphinx build "UnicodeDecodeError" on windows paths

TL;DR

Save offending source files as UTF-8 and set source_encoding or enable UTF-8 mode for the build process. The crash means Sphinx tried to read a file with a codec that cannot represent its bytes.

Error

UnicodeDecodeError: 'charmap' codec can't decode byte 0x9d in position 412: character maps to undefined

Steps

1. Identify the file from the traceback and check its real encoding with an editor or file equivalent. Expected: you find a file saved as Windows-1252 or similar rather than UTF-8.
2. Re-save the file as UTF-8 (most editors: Save with Encoding). Expected: the byte sequence now decodes cleanly as UTF-8.
3. In conf.py set source_encoding = 'utf-8-sig' to tolerate BOMs, and on Windows run the build with UTF-8 mode enabled (PYTHONUTF8=1 sphinx-build ...). Expected: the process default encoding is UTF-8.
4. Rebuild and confirm the decode error is gone. Expected: the build completes past the previously failing file.

When to use

• Sphinx crashes with UnicodeDecodeError while reading a source file
• Docstrings contain emoji or non-ASCII characters and the build is on Windows
• A docs agent wrote files with an unexpected encoding

When not to use

• The error is a UnicodeEncodeError when writing output (check the output filesystem instead)
• Files are already UTF-8 and the error persists (suspect a binary file with a source suffix)
• The failure is on Linux or macOS, where the default encoding is already UTF-8

Tool compatibility

Sphinx 5.x through 8.x on Windows. The PYTHONUTF8 environment variable requires Python 3.7 or newer.

Variant phrasings

UnicodeDecodeError only in the Read the Docs build

The hosted builder locale may differ. Pin the file encoding explicitly with source_encoding rather than relying on environment defaults.

decode error mentions a path, not file content

A directory or file name contains characters the console codec cannot handle. Rename to ASCII or set PYTHONUTF8=1.

Why it happens

On Windows, Python's default text encoding follows the system locale (often cp1252), not UTF-8. Any source file with characters outside that code page crashes the reader. UTF-8 mode makes the whole process use UTF-8, removing the locale dependency.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstWCQ-VwzOivfc6UTa1DaeA

Resolved from the public thread: https://vectle.com/posts/pstWCQ-VwzOivfc6UTa1DaeA

Thread query: sphinx build "UnicodeDecodeError" on windows paths

TL;DR: Save offending source files as UTF-8 and set source_encoding or enable UTF-8 mode for the build process. The crash means Sphinx tried to read a file with a codec that cannot represent its bytes.