UnicodeEncodeError latin-1は日本語ファイル名が原因
Pythonの requests でWordPressに画像をアップロードしようとしたら、「UnicodeEncodeError: 'latin-1’ codec can’t encode character」というエラーで止まった。画像の中身は普通のJPEGなのに、そもそも「latin-1」って何? そんな状態の方に向けた記事です。
この記事では、このエラーが何を意味しているのか、なぜ画像のアップロードで起きるのか、どう直せばいいのかを書きます。僕は移住前に都内でSEをしていて、今はこのブログの投稿をPythonで自動化しています。その作業中に、まさにこのエラーで止まりました。
読み終わるころには、エラーの原因に当たりをつけて、数行の修正で先に進めるようになるはずです。
こんなエラーが出ていませんか?
WordPressのREST APIで、画像を /wp-json/wp/v2/media に送ったときに、次のようなエラーが出るケースです。
UnicodeEncodeError: 'latin-1' codec can't encode characters in position 22-30: ordinal not in range(256)
日本語が1文字だけなら「can’t encode character '日’ in position 22」のように文字コード付きで、何文字か続いていると上のように「characters in position 22-30」と範囲で表示されます。数字は送ろうとした内容によって変わります。WordPressから返ってきたエラーではなく、Pythonがリクエストを送る前に止まっているのがポイントです。
結論:HTTPヘッダーに日本語を入れたのが原因
- HTTPの「ヘッダー」(リクエストに付ける付帯情報)には、日本語をそのまま入れられません
- Python標準の
http.client(requests も最終的にこれを使って送ります)は、ヘッダーの値を latin-1 という文字コードに変換してから送ります。latin-1 は英数字や欧文の記号・アクセント付き文字など256種類しか扱えないので、日本語が入っているとこのエラーになります - 画像のアップロードでは、ファイル名を
Content-Dispositionというヘッダーに入れて送るため、ファイル名が日本語だと、ここで引っかかります
直し方はシンプルで、ファイル名を英数字だけにすることです。僕はこの方法で直りました。
僕の場合:ファイル名が記事のキーワードだった
僕は、Pythonの requests でWordPressに画像をアップロードするプログラムを動かしていました。そこで出たのが、冒頭の「UnicodeEncodeError: 'latin-1’ codec can’t encode character」です。
原因は、Content-Disposition ヘッダーに入れていたファイル名が、日本語(記事のキーワード)になっていたことでした。ファイル名を日本語にしていたのに、特に理由はありません。プログラムを作ったときに、たまたまそうなっていただけです。
正直、原因に気づくまで少し悩みました。エラーメッセージに出てくる「latin-1」が何のことか分からなかったからです。調べたり、Claude(AIアシスタント)に聞いたりして、ようやく「HTTPヘッダーには日本語をそのまま入れられない」という話にたどり着きました。
ファイル名を featured-時刻.jpg のような英数字だけの名前に変えたら、エラーは出なくなりました。
なぜ latin-1 なのか
少しだけ仕組みの話をします。
HTTPの仕様(RFC 9110)では、ヘッダーの値は基本的に US-ASCII(半角英数字と記号)の範囲にとどめるものとされています。昔は ISO-8859-1(latin-1 と同じ文字コード)の文字も許されていた、という経緯も書かれています。
Pythonの http.client のソースコードを見ると(2026年11月時点)、ヘッダーの値が文字列なら encode('latin-1') で変換してから送る作りになっています。latin-1 で表せるのは256種類の文字だけなので、「日」のような日本語は変換できません。エラーメッセージの「ordinal not in range(256)」は、「この文字の番号は256の範囲に入っていない」という意味です。
つまり、エラーに出てくる latin-1 は「Pythonがヘッダーを送るときに使う文字コード」のことで、画像の中身とは関係ありません。
直し方:ファイル名を英数字にする
ここからは、実際の直し方です。下のコードは説明用に書いたもので、当時のコードそのものではありません。
エラーになる書き方
画像のデータをそのまま本文として送り、ファイル名を Content-Disposition ヘッダーで伝える書き方です。
import requests
# WP_USER・WP_APP_PASSWORD は、ユーザー名とアプリケーションパスワードに置き換え
filename = "日本語のキーワード.jpg" # ← ヘッダーに日本語が入る
with open("image.jpg", "rb") as f:
r = requests.post(
"https://example.com/wp-json/wp/v2/media",
auth=(WP_USER, WP_APP_PASSWORD),
headers={
"Content-Disposition": f'attachment; filename="{filename}"',
"Content-Type": "image/jpeg",
},
data=f.read(),
)
直した書き方
ファイル名を英数字だけにします。僕は featured-時刻.jpg のような名前にしました。時刻を入れておくと、毎回ちがう名前になります。
from datetime import datetime
filename = f"featured-{datetime.now():%Y%m%d%H%M%S}.jpg"
あとは同じコードで送れます。ちなみに、WordPressのソースを見ると(2026年11月時点)、この書き方で Content-Disposition ヘッダーがないと「No Content-Disposition supplied.」というエラー(400)が返る作りです。ヘッダー自体は外さず、中身のファイル名だけを変えてください。
参考:日本語のファイル名を送る正式な書き方(僕は試していません)
「どうしても日本語のファイル名で送りたい」という場合のために、仕様上の方法も紹介しておきます。
Content-Disposition の仕様(RFC 6266)には、filename* という書き方があります。ファイル名をUTF-8にしたうえで「%E6%97%A5」のような形(パーセントエンコード)に変換して送るもので、変換のルールは RFC 5987(現在は RFC 8187 に更新)で決められています。RFC 6266 では、filename* を理解できない古い受け手のために、英数字の filename も一緒に付ける書き方も紹介されています。
from urllib.parse import quote
name = "日本語のキーワード.jpg"
cd = f"attachment; filename=\"image.jpg\"; filename*=UTF-8''{quote(name, safe='')}"
こうすればヘッダーの中身は英数字と記号だけになるので、latin-1 のエラーは出ないはずです。
ただし、僕はこの方法を試していません。しかも、WordPressのソースコードを読んだ限りでは(2026年11月時点)、REST APIがファイル名として読み取っているのは filename だけで、filename* を読む処理は見当たりませんでした。そのため、この方法で送っても、WordPressに日本語のファイル名で保存されるとは限りません。試す場合は、自分の環境で結果を確認してください。
キーワードを入れたいなら、代替テキストやタイトルに
もし「画像検索を意識して、ファイル名にキーワードを入れたい」と考えているなら、ファイル名にこだわらなくても大丈夫です。
Googleの画像検索向けのガイドでは、ファイル名は画像の内容について「ごくわずかな手がかり」にとどまるとされ、代替テキスト(alt属性)が「最も重要な属性」と書かれています(2026年11月時点)。ファイル名は英数字にして、キーワードは代替テキストやタイトルに入れる、という分け方で十分だと思います。
WordPressのREST APIでは、アップロードしたあとに、画像のIDを指定して alt_text(代替テキスト)や title(タイトル)を更新できます。こちらはJSONの本文として送るので、日本語でも問題ありません。
media_id = r.json()["id"]
requests.post(
f"https://example.com/wp-json/wp/v2/media/{media_id}",
auth=(WP_USER, WP_APP_PASSWORD),
json={"alt_text": "日本語のキーワード", "title": "日本語のキーワード"},
)
なお、同じガイドには「キーワードを詰め込みすぎない」ことも書かれています。代替テキストは、画像の内容を短く説明する文にしておきましょう。
それでもアップロードできないとき
ファイル名を英数字にしてエラーが消えたあと、今度はWordPress側から別のエラーが返ってくることもあります。僕は同じ自動投稿の作業で、次のエラーにも引っかかりました。
- JSONで401「rest_cannot_create」が返る → rest_cannot_create(401)の原因|確認する順番
- 「403 Forbidden」だけのエラーページになる → ConoHa WINGでREST APIが403に|原因と直し方
- 「閲覧できません Powered by SiteGuard Lite」の画面になる → SiteGuard「閲覧できません」の直し方|ConoHa WING
latin-1 のエラーはPythonの中で起きるもの、上の3つはリクエストがサーバーに届いてから起きるもの、という違いがあります。どこで止まっているかを見ると、切り分けやすくなります。
まとめ
「UnicodeEncodeError: 'latin-1’」が出たときのポイントをまとめます。
- 画像の問題ではなく、HTTPヘッダーに日本語が入っていることが原因
- 画像アップロードなら、まず
Content-Dispositionのファイル名に日本語が入っていないかを見る - 直し方は、ファイル名を英数字だけにすること(僕はこれで直りました)
filename*を使う方法もあるが、WordPressで日本語のファイル名になるかは未確認- キーワードを入れたいなら、ファイル名ではなく代替テキストやタイトルに
「latin-1」という見慣れない言葉に戸惑うエラーですが、原因が分かれば直すのは数行です。同じところで手が止まっている方の参考になればうれしいです。



ディスカッション
コメント一覧
まだ、コメントがありません