Python on Windows: UnicodeEncodeError 'charmap' codec can't encode '✅' (✅) in print() — script crashes after work succeeds

A Python script that does its real work successfully (writes files, finishes its API calls, etc.) crashes at the end on a print() call that contains an emoji like ✅, ❌, ⚠️. The traceback looks like:

Traceback (most recent call last):
  File "convert.py", line 733, in main
    print(f"✅ {output_path}")
  File "...\Lib\encodings\cp1252.py", line 19, in encode
    return codecs.charmap_encode(input,self.errors,encoding_table)[0]
UnicodeEncodeError: 'charmap' codec can't encode character '✅' in position 0: character maps to <undefined>

This happens specifically on Windows with Python 3.x (3.6+) when stdout is piped/captured (e.g., from another tool, from MSYS/Git Bash, from a CI runner) and Python falls back to the legacy cp1252 ANSI code page for stdout encoding. The Windows console itself can usually print emojis these days, but the moment stdout is anything other than the native console, Python defaults to cp1252 — which has no mapping for any emoji codepoint.

Symptoms that point at this:

• Exit code != 0 even though the work was clearly done.
• The traceback ends in cp1252.py / charmap_encode.
• The failing character in the error is a high codepoint like ✅ (✅), ❌ (❌), ⚠ (⚠️).
• Works fine on Mac/Linux. Works fine in PowerShell on Windows. Fails when stdout is piped or when run under MSYS/Cygwin/Git Bash.

The annoying part: the real work completes before the crash. The PDF is written. The HTTP call returned. But the script's exit status is still 1, and any caller (Make, CI, shell script) treats the run as a failure.

Diagnostic order:

1. The traceback frame ending in cp1252.py / charmap_encode is the strong signal — this is Python's output encoder failing, not the program logic.
2. Confirm with python -c "import sys; print(sys.stdout.encoding)" in the same shell. Anything other than utf-8 on a script that prints emojis is a problem waiting to happen on Windows.
3. The codepoint reported (✅, ❌, etc.) tells you exactly which print statement is responsible — search the source for the codepoint or the visible glyph.
4. Note that the script's file output is unaffected — only sys.stdout (or sys.stderr) writes hit the cp1252 path. So if outputs are on disk, the work itself is done.

Why this happens: on Windows, when stdout is not a "real" console (i.e., it's redirected, captured by a parent process, or running under MSYS/Cygwin emulated terminal), Python 3 falls back to the system ANSI code page, which is cp1252 on US/Western Windows. That codec covers Latin-1 + extras but no emoji and no extended Unicode. PEP 540 (-X utf8 / PYTHONUTF8=1, Python 3.7+) tried to fix this but isn't on by default until Python 3.15.

Reproduced the failure by running a Python script under Git Bash on Windows 11 (cp1252 console code page, Python 3.14). The script wrote a PDF successfully, then crashed on print(f"✅ {path}") with the traceback above. Set export PYTHONIOENCODING=utf-8 in the same shell, re-ran the identical command. Script printed ✅ <path> cleanly and exited 0. PDF identical to the previous (successful) run, confirming the work itself was always succeeding — only the post-success print was failing.