---
name: runbook-windows-python
description: Windows + Python 開発で遭遇する落とし穴の Runbook。UnicodeEncodeError、cp932、rich、PowerShell、Windows Terminal、legacy console、PYTHONIOENCODING、文字コード関連のエラーが出た時に自動参照。
disable-model-invocation: false
user-invocable: true
effort: low
shell: powershell
---

# /runbook-windows-python — Windows + Python 落とし穴 Runbook

Windows 環境で Python を動かす際に実際に遭遇した落とし穴と対処を蓄積する Runbook。
知識文書ではなく、**症状→原因→対処** の3行で再発防止できる実行可能メモとして育てる。

## 使い方

1. エラー遭遇時、症状キーワードで本ファイルを検索
2. 該当ケースの対処を即時適用
3. 新規ケースは末尾 Gotchas に3行で追記（`## Gotchas 追記ルール` 参照）

## Gotchas

### 1. `UnicodeEncodeError: 'cp932' codec can't encode character`

- **症状**: Python スクリプト実行時に日本語や Unicode 記号（`✓`, `→` 等）で `UnicodeEncodeError: 'cp932' codec can't encode character '\uXXXX'` が発生
- **原因**: Windows legacy console の既定エンコーディングが cp932 (Shift_JIS)。Python の標準出力がコンソールを継承し、Unicode 文字を cp932 に変換できずクラッシュ
- **対処**: 環境変数 `PYTHONIOENCODING=utf-8` を設定して Python の stdio を UTF-8 化する
  - PowerShell: `$env:PYTHONIOENCODING='utf-8'`
  - bash (Git Bash 等): `export PYTHONIOENCODING=utf-8`
  - 単発実行: `PYTHONIOENCODING=utf-8 python script.py`
  - 永続化: システム環境変数に追加、または `.env` / プロジェクト起動スクリプトに記述

### 2. `rich` ライブラリが `LegacyWindowsTerm` で書き込み失敗

- **症状**: `rich.console.Console` を使う CLI ツール（click + rich 等）が `_win32_console.py` の `write_text` で `UnicodeEncodeError` を出してクラッシュ。ステータスアイコン `\u2713` (✓) や絵文字で特に発生
- **原因**: rich が Windows の legacy console (cmd.exe / 旧コンソールホスト) を検出すると `legacy_windows_render` 経由で出力するが、そのパスが OS の cp932 API に依存する
- **対処**: 以下のいずれか
  - **Windows Terminal を使う**（推奨・根本対処）: legacy console ではないため rich が新レンダラに切替わる
  - `PYTHONIOENCODING=utf-8` を設定
  - rich 側で `Console(legacy_windows=False)` を明示（呼び出し元の改修が必要）

## Gotchas 追記ルール

新規ケースは必ず以下の3行フォーマットで追加する:

```
- **症状**: <エラーメッセージ or 目に見える挙動を1行で>
- **原因**: <なぜ起きるかを1行で>
- **対処**: <コピペで解決できるコマンド or 手順を1行で>
```

禁止事項:

- 一般論で書かない（「文字コードに気をつけましょう」ではなく具体的な対処コマンド）
- 背景解説の長文化（詳細は外部リンクに逃がす）
- 未検証の対処を書かない（実際に動いたものだけ）