Windows + Python 開発で遭遇する落とし穴の Runbook。UnicodeEncodeError、cp932、rich、PowerShell、Windows Terminal、legacy console、PYTHONIOENCODING、文字コード関連のエラーが出た時に自動参照。
Windows 環境で Python を動かす際に実際に遭遇した落とし穴と対処を蓄積する Runbook。 知識文書ではなく、症状→原因→対処 の3行で再発防止できる実行可能メモとして育てる。
## Gotchas 追記ルール 参照)UnicodeEncodeError: 'cp932' codec can't encode character✓, → 等)で UnicodeEncodeError: 'cp932' codec can't encode character '\uXXXX' が発生PYTHONIOENCODING=utf-8 を設定して Python の stdio を UTF-8 化する
$env:PYTHONIOENCODING='utf-8'export PYTHONIOENCODING=utf-8PYTHONIOENCODING=utf-8 python script.py.env / プロジェクト起動スクリプトに記述rich ライブラリが LegacyWindowsTerm で書き込み失敗rich.console.Console を使う CLI ツール(click + rich 等)が _win32_console.py の write_text で UnicodeEncodeError を出してクラッシュ。ステータスアイコン \u2713 (✓) や絵文字で特に発生legacy_windows_render 経由で出力するが、そのパスが OS の cp932 API に依存するPYTHONIOENCODING=utf-8 を設定Console(legacy_windows=False) を明示(呼び出し元の改修が必要)新規ケースは必ず以下の3行フォーマットで追加する:
- **症状**: <エラーメッセージ or 目に見える挙動を1行で>
- **原因**: <なぜ起きるかを1行で>
- **対処**: <コピペで解決できるコマンド or 手順を1行で>
禁止事項: