メインコンテンツへスキップ
見出し画像

Windows の Python で PYTHONIOENCODING=utf-8 が効かないときは -I フラグを疑う

    Windows の Python で日本語が化ける。PYTHONIOENCODING=utf-8 を設定したのに直らない。そんなときは、Python の起動オプションに -I が付いていないか確認してください。

    **-I(分離モード)は PYTHON で始まる環境変数をすべて無視します。PYTHONIOENCODING も例外ではありません。** 直し方は -X utf8 を使うことです。

    この記事では、文字化けの原因、-I フラグとの組み合わせで起きる落とし穴、そして解決方法を、実際に遭遇したときの記録をもとに書きます。

    起きたこと

    Claude Code から Python スクリプトを実行したところ、日本語の出力が化けました。

    たとえば次のようなコマンドです。

    python -c "print('日本語')"

    出力に表示される日本語が文字化けし、読めない状態でした。

    「Windows の Python は標準出力のエンコーディングが cp932 だから、UTF-8 にすればいい」と思い、環境変数を設定しました。

    set PYTHONIOENCODING=utf-8

    ところが、私の環境では python -I で実行していたため、この環境変数を設定しても文字化けは直りませんでした。

    環境

    - OS: Windows 11
    - Python 3(python -I で実行)
    - Claude Code(VS Code 拡張)
    - 確認日: 2026-10-14

    原因

    2つのことが重なっています。

    1. Windows の Python は、標準出力のエンコーディングが既定で cp932

    日本語の Windows では、コンソールのコードページが cp932(Shift_JIS 系)です。Python はこのコードページを標準出力のエンコーディングとして使います。UTF-8 で書いたスクリプトの出力を、cp932 として扱おうとするために文字化けが起きます。

    **2. -I フラグは PYTHON で始まる環境変数を無視する**

    -I は Python の「分離モード(isolated mode)」を有効にするオプションです。公式ドキュメントにはこう書かれています。

    > Run Python in isolated mode. This also implies -E, -P and -s options. In isolated mode sys.path contains neither the script's directory nor the user's site-packages directory. All PYTHON* environment variables are ignored, too.

    つまり、PYTHONIOENCODING も PYTHONUTF8 も、-I を付けた時点で無視されます。

    Claude Code が Python を -I 付きで起動するケースでは、環境変数による対策が丸ごと効かなくなります。これが「設定したのに直らない」の正体です。

    直し方

    方法1: -X utf8 を付ける(おすすめ)

    python -I -X utf8 -c "print('日本語')"

    -X utf8 は環境変数ではなくコマンドラインオプションなので、-I(分離モード)と一緒に使えます。Python の UTF-8 モードが有効になり、標準入出力のエンコーディングが UTF-8 になります。

    方法2: スクリプトの中で sys.stdout.reconfigure を使う

    import sys
    sys.stdout.reconfigure(encoding="utf-8")
    print("日本語")

    スクリプトの先頭で標準出力のエンコーディングを変える方法です。-I の影響を受けません。ただし、スクリプトごとに書く必要があります。

    方法3: プロジェクトの settings.json に PYTHONIOENCODING を設定する

    Claude Code のプロジェクト設定(.claude/settings.json)の env に環境変数を書いておく方法です。

    {
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }

    この方法は -I なしで Python を実行する場合には有効です。ただし、-I 付きの実行では環境変数が無視されるため効きません。-I を使う環境では方法1か方法2を選んでください。

    確認のしかた

    -I 付きで PYTHONIOENCODING=utf-8 を設定した実行と、-I -X utf8 での実行を比べます。

    set PYTHONIOENCODING=utf-8
    python -I -c "print('日本語')"

    この実行では文字化けします。-I が PYTHONIOENCODING を無視するためです。

    python -I -X utf8 -c "print('日本語')"

    こちらは正しく「日本語」と表示されます。

    私の環境では、-I 付きで PYTHONIOENCODING=utf-8 を付けた実行は化け、-I -X utf8 に変えると正しく表示されました。

    似た症状・注意点

    - Python 3.15(2026年10月リリース)では、PEP 686 により UTF-8 がすべてのプラットフォームで既定のエンコーディングになりました。Python 3.15 以降ではこの問題は起きにくくなりますが、Python 3.12〜3.14 を使っている環境では引き続き対策が必要です
    - PYTHONUTF8=1 という環境変数でも UTF-8 モードを有効にできますが、これも PYTHON で始まる環境変数なので -I では無視されます。-X utf8 を使ってください
    - Windows PowerShell から実行する場合も同じ問題が起きます。Git Bash でも PowerShell でも、-I の挙動は変わりません

    関連記事

    - Claude Code の deny は確認で通る。本当に止めるなら PreToolUse hook を使う


    参考
    - Python コマンドラインと環境 — Python 3 ドキュメント
    - Python UTF-8 モード — Python 3 ドキュメント

     
     
    会社員のエンジニア、まだみです。ニュースや統計で「なんで?」と引っかかったことを、資料とデータで掘って書いています。SalesforceやAIの話も。好きなものはホラー映画、ミステリー小説、日本語ラップ、タコス。

    あなたへのおすすめ