ErrorNotes

Pythonにおける「UnicodeEncodeError: ascii codec can't encode character」の解決

inte🐍 Python2026-03-27| このエラーは、あらゆるオペレーティングシステム（Windows、Linux、macOS）および任意のPython 3バージョンで発生する可能性があります。特に、非ASCII文字を含むファイル、データベース、ネットワークストリームなどの外部リソースと対話する際、Pythonがデフォルトで「ascii」エンコーディングを使用したり、明示的に指定されたりした場合によく発生します。

Error Message

UnicodeEncodeError: 'ascii' codec can't encode character '\u00e9' in position 1: ordinal not in range(128)
#python#unicode#encoding#ascii#utf-8

「UnicodeEncodeError: ascii codec can't encode character」を理解する

このようなエラーを目にした場合、Pythonのエンコーディングに関する典型的な問題に遭遇しています。

UnicodeEncodeError: 'ascii' codec can't encode character '\u00e9' in position 1: ordinal not in range(128)

このエラーは、Pythonコードが標準ASCII範囲（0-127）外の文字を含む文字列を、asciiコーデックを使用してバイトシーケンスに変換しようとしていることを意味します。例えば、文字'\u00e9'は'é'（e-アキュート）であり、多くのヨーロッパ言語で一般的ですが、基本的な128個のASCII文字には含まれません。

Python 3では、デフォルトで文字列をUnicodeとして扱います。これは非常に便利です。しかし、その文字列を外部システム（ファイルへの書き込み、ネットワーク経由での送信、ターミナルへの出力など）に送信する必要がある場合、バイトシーケンスに変換する必要があります。この変換プロセスはエンコーディングと呼ばれます。PythonがUnicode文字列をasciiを使用してエンコードしようとし、'é'のような文字に遭遇すると、このUnicodeEncodeErrorをスローします。

これは通常、次のようなシナリオで発生します。

  • エンコーディングを明示的に指定せずにファイルI/O（読み書き）を実行している場合。
  • 特定のエンコーディングを期待するデータベースやAPIとやり取りしているときに、Pythonのデフォルトまたは誤った明示的なエンコーディングが使用されている場合。
  • 非ASCII文字を含む文字列を、エンコーディングが正しく設定されていない（例：UTF-8に設定されていない）ターミナルに出力しようとしている場合。
  • 非ASCII文字を含む文字列に対して、明示的に.encode('ascii')を呼び出している場合。

ステップバイステップの修正：UTF-8エンコーディングを明示的に使用する

根本的な解決策は、ほとんどの場合、エンコーディングとして'utf-8'を明示的に指定することです。UTF-8は、事実上あらゆる言語のあらゆる文字を表現できます。

1. ファイルI/Oの修正

ファイルの読み書きのために開くときは、常にencoding='utf-8'パラメーターを指定してください。これにより、PythonはUnicode文字列からバイトへの変換（書き込み時）またはバイトからUnicode文字列への変換（読み取り時）を正しく処理します。

ファイルへの書き込み：

# デフォルトのシステムエンコーディング（古いシステム/設定ではASCIIであることが多い）で'my_file.txt'が開かれたり、環境が誤って設定されている場合、UnicodeEncodeErrorを引き起こす可能性があります。
# with open('my_file.txt', 'w') as f:
#     f.write('Café latte')

# 正しい方法：UTF-8エンコーディングを明示的に指定する
content_to_write = 'This is a test with a special character: Café latte and Résumé.'
file_path = 'unicode_example.txt'

try:
    with open(file_path, 'w', encoding='utf-8') as f:
        f.write(content_to_write)
    print(f"Successfully wrote to '{file_path}' with UTF-8 encoding.")
except Exception as e:
    print(f"Error writing file: {e}")

ファイルからの読み込み：

同様に、読み込み時にはencoding='utf-8'を指定して、バイトをUnicode文字として正しく解釈するようにします。

try:
    with open(file_path, 'r', encoding='utf-8') as f:
        read_content = f.read()
    print(f"Successfully read from '{file_path}':")
    print(read_content)
except Exception as e:
    print(f"Error reading file: {e}")

2. 手動での文字列エンコーディング/デコーディングの修正

文字列をバイトに手動でエンコードしたり、バイトを文字列にデコードしたりする場合は、'utf-8'を使用していることを確認してください。

my_unicode_string = "Bonjour, comment ça va? Résumé." # 'ç'と'é'を含む

# これはUnicodeEncodeErrorを引き起こします：
# encoded_ascii_bytes = my_unicode_string.encode('ascii')

# 正しい方法：UTF-8バイトにエンコードする
encoded_utf8_bytes = my_unicode_string.encode('utf-8')
print(f"UTF-8 encoded bytes: {encoded_utf8_bytes}")

# UTF-8バイトから文字列に戻すには
decoded_string = encoded_utf8_bytes.decode('utf-8')
print(f"Decoded string: {decoded_string}")

3. コンソール/スクリプトのデフォルトのための環境変数

問題がPythonのコンソール出力のデフォルトエンコーディングや、環境の解釈に起因することもあります。特にLinux/macOS、またはスクリプト実行の場合、環境変数を設定することが役立ちます。

Linux/macOSの場合：

スクリプトを実行する前に、LANGまたはLC_ALLをUTF-8ロケールに設定します。Python 3固有のI/OにはPYTHONIOENCODINGも設定できます。

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
export PYTHONIOENCODING=utf-8
python your_script.py

Windowsの場合：

Python 3ではあまり一般的ではありませんが、コンソール出力で問題が発生している場合は、現在のセッションでコンソールのコードページをUTF-8（65001）に設定してみてください。その後、そのコンソールからスクリプトを実行します。

chcp 65001
set PYTHONIOENCODING=utf-8
python your_script.py

4. データベースとの連携

データベースにデータを挿入したり取得したりする場合は、データベース接続がUTF-8を使用するように構成されていることを確認してください。ほとんどのデータベースドライバーには、このためのパラメーターがあります。

psycopg2（PostgreSQL）の例：

import psycopg2

try:
    conn = psycopg2.connect(
        dbname='your_db',
        user='your_user',
        password='your_password',
        host='localhost',
        client_encoding='UTF8' # Unicodeを処理するために重要
    )
    cursor = conn.cursor()

    # 非ASCII文字を含むデータを挿入
    cursor.execute("INSERT INTO my_table (text_column) VALUES (%s)", ("Café latte",))
    conn.commit()

    # データを取得
    cursor.execute("SELECT text_column FROM my_table WHERE text_column = %s", ("Café latte",))
    result = cursor.fetchone()
    print(f"Retrieved from DB: {result[0]}")

    cursor.close()
    conn.close()
    print("Database operation successful with UTF-8.")

except Exception as e:
    print(f"Database error: {e}")

5. ネットワークリクエストの処理

requestsのようなライブラリは、JSONペイロードのUTF-8エンコーディングを自動的に処理することが一般的です。ただし、フォームデータやURL内の生の文字列を扱う場合は、明示的にエンコードする必要があるかもしれません。

import requests
import urllib.parse

# JSONペイロードの場合、requestsは通常UTF-8を正しく処理します
json_data = {'name': 'Résumé'}
response = requests.post('http://example.com/api', json=json_data)
print(f"API response (JSON): {response.text}")

# URLパラメーターの場合、UTF-8でurllib.parse.quoteを使用します
query_string_param = "Café"
encoded_param = urllib.parse.quote(query_string_param, encoding='utf-8')
print(f"URL-encoded param: {encoded_param}") # 出力: Caf%C3%A9

# URLでの使用例
# response = requests.get(f'http://example.com/search?q={encoded_param}')
# print(f"API response (URL): {response.text}")

6. 意図的なエラー処理（注意して使用）

ごくまれに、どうしてもASCIIで出力する必要がある場合（例：ASCIIのみを受け入れるレガシーシステム）、非ASCII文字が出現する可能性があるとわかっている場合は、エンコーディング中にエラーハンドラーを使用できます。これはデータ損失または変更を意味することに注意してください。

my_string = "Résumé with a smile 😊"

# 'ignore': エンコードできない文字を破棄する
ignored_bytes = my_string.encode('ascii', errors='ignore')
print(f"Ignore errors: {ignored_bytes}") # 出力: b'Rsum with a smile '

# 'replace': 文字を疑問符に置き換える
replaced_bytes = my_string.encode('ascii', errors='replace')
print(f"Replace errors: {replaced_bytes}") # 出力: b'R?sum? with a smile ??'

# 'xmlcharrefreplace': XML文字参照に置き換える
xml_bytes = my_string.encode('ascii', errors='xmlcharrefreplace')
print(f"XML char ref: {xml_bytes}") # 出力: b'Résumé with a smile 😊'

通常、データ損失を明示的に理解し受け入れない限り、errors='ignore'やerrors='replace'の使用は避けてください。

検証手順

修正を適用した後、問題が解決されたことを確認します。

  • コードを再実行する： 問題のあるPythonスクリプトまたはコードのセクションを再度実行します。

  • 出力を確認する：

    ファイルに書き込んでいた場合は、テキストエディター（VS Code、Notepad++、Sublime Textなど）をUTF-8表示に設定してファイルを開きます。すべての特殊文字が正しく表示されていることを確認します。

    • コンソールに出力していた場合は、ターミナルで文字が期待どおりに表示されていることを確認します。
    • ネットワーク経由またはデータベースにデータを送信していた場合は、受信側でデータが正しい文字で送信および保存されていることを確認します。

  • アサーションを追加する： 重要なデータパスについては、I/Oまたは変換後の文字列コンテンツを検証する単体テストまたはアサーションの追加を検討してください。

予防とデバッグのヒント

  • UTF-8に標準化する： ソースコードファイル、データベース接続、Webレスポンス、ファイルI/Oなど、すべてにおいてUTF-8をデフォルトのエンコーディングにしてください。これは国際的なテキストにとって最も堅牢なエンコーディングです。

  • エディターのエンコーディングを確認する： コードエディターがPythonファイルをUTF-8として保存することを確認してください。ほとんどの最新のエディターはデフォルトでこれを行いますが、確認する価値はあります。

  • 明示的にする： 外部データソースを扱う場合、デフォルトのエンコーディングに依存しないでください。常にencoding='utf-8'を指定してください。

  • sys.getdefaultencoding()とsys.getfilesystemencoding()を使用する： これらはPythonがどのようなデフォルトエンコーディングであると考えているかについての洞察を与えますが、これらの情報に頼るよりも'utf-8'を明示的に指定する方が常に安全であることを忘れないでください。

  • オンラインツールを使ったデバッグ： 変換または送信された文字列を扱っていて、エンコーディングの問題を疑う場合、オンラインツールを使ってそれらを素早く検査したり変換したりすることがよくあります。例えば、URLエンコードされた後に発生するUnicodeEncodeErrorのトラブルシューティングをしている場合、URLエンコーダー/デコーダーを使って文字が実際にどのように表現されているかを確認することがあります。

https://toolcraft.app/en/tools/developer/url-encoderにあるToolCraftのURLエンコーダー/デコーダーや、https://toolcraft.app/en/tools/developer/base64-encoderにあるBase64エンコーダー/デコーダーは、このような場合に便利です。これらは完全にブラウザ内で動作するため、データが自分のマシンから離れる心配はありません。

Related Error Notes

PythonのMultiprocessingで発生する「TypeError: cannot pickle」の解決方法

TypeError: cannot pickle '<lambda>' object

Pythonの「TypeError: method() takes 1 positional argument but 2 were given」を解決する

TypeError: my_method() takes 1 positional argument but 2 were given

pipでPythonパッケージをインストールする際の「error: externally-managed-environment」を修正する

error: externally-managed-environment