Python
PR

Pythonのファイル読み書き|open・with・encoding指定と文字化けの直し方

Pythonのファイル読み書き|open・with・encoding指定と文字化けの直し方
hr
記事内に商品プロモーションを含む場合があります

Python でテキストファイルを読み書きするのは、open() を使えば数行でできます。ところが、Windows では「UnicodeDecodeError が出た」「書き出したファイルが文字化けした」というトラブルがよく起きます。原因のほとんどは、文字コード(encoding)を指定していないことです。

この記事では、次のことを、Windows 11 の Python 3.12 で実際に動かした結果つきで解説します。

  • open() と with 文を使った基本の読み書き
  • モード(r・w・a・x・b)の使い分け
  • encoding を省略したときの文字コードが Windows と Linux で違う理由
  • utf-8・utf-8-sig・cp932 の使い分けと、UnicodeDecodeError の直し方
  • 改行コード(\r\n)の扱いと、pathlib の read_text・write_text

文字コードそのものの仕組みは「文字コードとは?」で解説しています。サンプルは、好きなフォルダーに sample.py などの名前で保存し、PowerShell やコマンドプロンプトで py sample.py のように実行してください。

基本の読み書き:open() と with 文

ファイルを読み書きするときは、open(ファイル名, モード, encoding=文字コード) でファイルを開き、with 文と組み合わせて使います。次のプログラムは、memo.txt に 2 行書き込んでから、読み込んで表示します。

with open("memo.txt", "w", encoding="utf-8") as f:
    f.write("こんにちは\n")
    f.write("Python\n")

with open("memo.txt", "r", encoding="utf-8") as f:
    text = f.read()

print(repr(text))
print(f.closed)
'こんにちは\nPython\n'
True

repr() は、改行などの見えない文字を \n のように見える形で表示する関数です。write() は改行を自動では付けないので、行の終わりには自分で \n を書きます。

2 行目の True は、ファイルが閉じていることを表します。with 文を使うと、ブロック(字下げした部分)を抜けたときに、エラーが起きた場合も含めて自動でファイルを閉じてくれます。f.close() の書き忘れを防げるので、ファイルは with 文で開くと覚えておきましょう。

1 行ずつ読む

ファイルを 1 行ずつ処理したいときは、ファイルを for 文で回します。大きなファイルでも、全体を一度にメモリーに読み込まずに済みます。

with open("memo.txt", encoding="utf-8") as f:
    for line in f:
        print(repr(line))
'こんにちは\n'
'Python\n'

読んだ行には、最後に改行 \n が付いたままです。改行のない文字列のリストがほしいときは f.read().splitlines() を使うと、['こんにちは', 'Python'] が得られます。モードを省略すると "r"(読み込み)になります。

モード(r・w・a・x・b)の使い分け

open() の 2 番目の引数で、ファイルをどう開くかを指定します。よく使うのは次のとおりです。

モード意味ファイルがあるときファイルがないとき
r読み込み(省略時)先頭から読むFileNotFoundError
w書き込み中身を消して書き直す新しく作る
a追記末尾に書き足す新しく作る
x新規作成FileExistsError新しく作る
bバイナリ(rb・wb のように組み合わせる)文字列ではなくバイト列(bytes)で読み書きする

w・a・x の違いを実際に試してみます。

# w:上書き a:追記 x:新規作成のみ
with open("log.txt", "w", encoding="utf-8") as f:
    f.write("1行目\n")
with open("log.txt", "a", encoding="utf-8") as f:
    f.write("2行目\n")
with open("log.txt", encoding="utf-8") as f:
    print(repr(f.read()))

with open("log.txt", "w", encoding="utf-8") as f:
    f.write("上書き\n")
with open("log.txt", encoding="utf-8") as f:
    print(repr(f.read()))

try:
    with open("log.txt", "x", encoding="utf-8") as f:
        f.write("新規\n")
except FileExistsError as e:
    print(e)
'1行目\n2行目\n'
'上書き\n'
[Errno 17] File exists: 'log.txt'

注意したいのは w モードは開いた瞬間に中身が消えることです。大事なファイルを w で開くと、何も書かなくても空になります。「すでにあるファイルを壊したくない」ときは x モードを使うと、上書きの代わりに FileExistsError で止まります。

ないファイルを r で開くと FileNotFoundError: [Errno 2] No such file or directory になります。そのときは、ファイル名のつづりと「どのフォルダーで実行したか」を確認します。相対パス(memo.txt のようにフォルダーを書かない指定)は、プログラムの置き場所ではなく、コマンドを実行したときのフォルダーから探されます。

encoding を省略すると Windows と Linux で結果が変わる

encoding を書かずに open() すると、Python は OS の言語設定(ロケール)から文字コードを決めます。公式ドキュメント(Python 3.12 の open())にも「encoding を指定しない場合はプラットフォームに依存し、locale.getencoding() の値が使われる」と書かれています。この PC で、何が使われるかを確かめてみます。

import locale
import sys

print(locale.getpreferredencoding(False))
print(locale.getencoding())
print(sys.flags.utf8_mode)
cp932
cp932
0

日本語版 Windows では cp932(Windows の Shift_JIS)でした。つまり encoding を省略して書き込むと、UTF-8 ではなく Shift_JIS 系のファイルができます。実際に、書き込まれたバイトを見てみます。

with open("default.txt", "w") as f:
    f.write("日本語\n")

with open("default.txt", "rb") as f:
    print(f.read())
b'\x93\xfa\x96{\x8c\xea\r\n'

「日本語」が 1 文字 2 バイト(93 FA、96 7B、8C EA)の Shift_JIS で保存されています。一方、言語設定が UTF-8 の Linux や macOS では、同じプログラムで UTF-8 のファイルができます。同じコードなのに、動かす PC によって結果が変わるのが、encoding を省略する危険なところです。

テキストモードの open が行う 2 つの変換の図。書き込みでは、文字列 日本語 と改行 バックスラッシュ n が、改行の変換で バックスラッシュ r バックスラッシュ n になり、encode で bytes の 93 FA 96 7B 8C EA 0D 0A としてファイルに書かれる。encoding を省略したこの PC では cp932 が使われ、日本語は 1 文字 2 バイト、改行は 0D 0A の 2 バイト。読み込みでは、ファイルの bytes を encoding の文字コードで decode し、改行を バックスラッシュ n にそろえて文字列にする。文字コードが合わないと UnicodeDecodeError か文字化けになる。rb と wb のバイナリモードはどちらの変換もしない。
図 1:テキストモードの open は、文字コードと改行を変換して読み書きする

よくあるエラー:UTF-8 のファイルを Windows で読む

VS Code や Linux で作った UTF-8 のファイルを、Windows で encoding なしで読むと、cp932 として読もうとしてエラーになります。

# UTF-8 で保存されたファイル(VS Code や Linux で作ったものなど)
with open("test.txt", "w", encoding="utf-8") as f:
    f.write("テスト結果: OK\n")

# encoding を書かずに読む
with open("test.txt") as f:
    print(f.read())
UnicodeDecodeError: 'cp932' codec can't decode byte 0x86 in position 2: illegal multibyte sequence

エラー文の 'cp932' codec can't decode は「cp932 として読めないバイトがあった」という意味です。直し方は、読み込みの open() に encoding="utf-8" を付けるだけです。読むときも書くときも、encoding は必ず書くのがいちばん確実な対策です。

encoding の書き忘れを見つける・既定を UTF-8 にする

Python 3.10 から(PEP 597)、-X warn_default_encoding を付けて実行すると、encoding を省略した open() の場所を警告で教えてくれます。先ほどの default.txt のプログラムを sample.py として実行した結果です(パスは一部省略)。

py -X warn_default_encoding sample.py
C:\...\sample.py:1: EncodingWarning: 'encoding' argument not specified
  with open("default.txt", "w") as f:
b'\x93\xfa\x96{\x8c\xea\r\n'

また、UTF-8 モードを有効にすると、encoding を省略したときの既定が UTF-8 になります。-X utf8 を付けて実行するか、環境変数 PYTHONUTF8 を 1 にします。PowerShell では次のように設定します(そのウィンドウを閉じるまで有効です)。

$env:PYTHONUTF8 = "1"

この状態で最初の確認プログラムを実行すると utf-8・cp932・1 と表示され、default.txt も UTF-8(1 文字 3 バイト)で書かれました。locale.getencoding() は cp932 のままですが、open() の既定は UTF-8 に変わります。

環境encoding を省略したときの文字コード
日本語版 Windows・Python 3.12(この記事で確認)cp932
同上で -X utf8 または PYTHONUTF8=1UTF-8
Linux・macOS言語設定(ロケール)しだい。UTF-8 の言語設定なら UTF-8
Python 3.15 以降UTF-8(UTF-8 モードが既定で有効)

最後の行は PEP 686 による変更です。2026 年 10 月 9 日公開の Python 3.15 の「What’s New」に、encoding を省略した open() が UTF-8 を使うこと、元に戻すには PYTHONUTF8=0 を使うことが書かれています(2026 年 10 月 18 日に公式サイトで確認。3.15 での動作は試していません)。同じページでも、バージョン間の互換性のため encoding を明示することが勧められています。

よく使う encoding:utf-8・utf-8-sig・cp932

encoding使う場面
utf-8基本はこれ。プログラム・設定ファイル・Web・Linux とやり取りするファイル
utf-8-sigBOM(先頭の目印 EF BB BF)付きの UTF-8。Excel で開く CSV を書くとき、Excel が書き出した CSV を読むとき
cp932Windows の古いソフトや業務システムが出す Shift_JIS のファイル

BOM 付きのファイルは utf-8-sig で読む

BOM 付きの UTF-8 を utf-8 で読むと、先頭に見えない文字 \ufeff が残ります。画面では見えないため、「1 列目の見出しが "名前" と一致しない」というバグがよく起きます。BOM 付きで書いた CSV を、utf-8 と utf-8-sig で読み比べてみます。

import csv

with open("score.csv", "w", encoding="utf-8-sig", newline="") as f:
    writer = csv.writer(f)
    writer.writerow(["名前", "点数"])
    writer.writerow(["佐藤", 80])

for enc in ["utf-8", "utf-8-sig"]:
    with open("score.csv", encoding=enc, newline="") as f:
        for row in csv.DictReader(f):
            print(enc, row)
utf-8 {'\ufeff名前': '佐藤', '点数': '80'}
utf-8-sig {'名前': '佐藤', '点数': '80'}

utf-8 で読むと、row["名前"] は KeyError になります。utf-8-sig は BOM がない UTF-8 も正しく読めた(試して確認)ので、UTF-8 の CSV を読むときは utf-8-sig にしておくと安心です。BOM の使い分けは「UTF-8とは?」で解説しています。

Shift_JIS は shift_jis ではなく cp932 を指定する

Windows の Shift_JIS には「髙」(はしごだか)や「①」のような Windows 独自の文字があり、Python の shift_jis では扱えません。"髙橋さん ①".encode("shift_jis") を実行すると 'shift_jis' codec can't encode character '\u9ad9' というエラーになり、cp932 なら問題なく変換できました。

Windows で作られた Shift_JIS のファイルは cp932 で読み書きしましょう。Shift_JIS と cp932 の違いは「Shift_JISとは?」で詳しく解説しています。

UnicodeDecodeError の再現と対処

今度は逆に、cp932 で保存されたファイルを UTF-8 として読んでみます。

# Shift_JIS(cp932)で保存されたファイルを用意する
with open("sjis.txt", "w", encoding="cp932") as f:
    f.write("売上データ\n")

# UTF-8 として読もうとする
with open("sjis.txt", encoding="utf-8") as f:
    print(f.read())
UnicodeDecodeError: 'utf-8' codec can't decode byte 0x94 in position 0: invalid start byte

「0 バイト目の 0x94 は、UTF-8 として正しくない」という意味です。いちばん良い直し方は、ファイルの本当の文字コードを指定すること(この場合は encoding="cp932")です。文字コードが分からないときは、サクラエディタや VS Code でファイルを開くと、画面の下の方に文字コードが表示されます。

errors 引数で、読めない部分の扱いを変える

ログの一部が壊れているなど、「読めない部分があっても、とにかく最後まで読みたい」ときは errors を指定します。同じ sjis.txt を、errors を変えて UTF-8 で読んだ結果です。

for mode in ["strict", "replace", "ignore", "backslashreplace"]:
    try:
        with open("sjis.txt", encoding="utf-8", errors=mode) as f:
            print(mode, repr(f.read()))
    except UnicodeDecodeError as e:
        print(mode, "エラー:", e)
strict エラー: 'utf-8' codec can't decode byte 0x94 in position 0: invalid start byte
replace '����f�[�^\n'
ignore 'f[^\n'
backslashreplace '\\x94\\x84\\x8f\\xe3\\x83f\\x81[\\x83^\n'
errors読めないバイトの扱い向いている場面
strict(省略時)エラーで止まる普段はこれ。間違いにすぐ気づける
replace� に置き換えるログの調査など、壊れた場所を目で見たいとき
ignore黙って捨てる基本は使わない(データが消えたことに気づけない)
backslashreplace\x94 のような形で残すどんなバイトだったかを後で調べたいとき

ignore では日本語がすべて消え、f[^ だけが残りました。errors はエラーを消すための道具ではなく、壊れたデータを扱うための道具です。文字コードの指定を間違えたまま errors で黙らせるのはやめましょう。

エラーにならずに文字化けすることもある

文字コードを間違えても、エラーになるとは限りません。UTF-8 のファイルを cp932 で読むと、次のようにエラーなしで文字化けすることがあります。

with open("utf8.txt", "w", encoding="utf-8") as f:
    f.write("売上データ\n")

with open("utf8.txt", encoding="cp932") as f:
    print(repr(f.read()))
'螢イ荳翫ョ繝シ繧ソ\n'

「縺」「繧」「繝」が目立つ文字化けは、UTF-8 を Shift_JIS として読んだときの典型です。このような文字化けした文字列を手に入れてしまったときは、文字化け復元ツールに貼り付けると、元の文字コードの組み合わせを推測して復元候補を表示できます。

UTF-8 と cp932 のどちらか分からないファイルを読む

UTF-8 と Shift_JIS のファイルが混ざっているフォルダーを処理するときは、「まず utf-8-sig で読み、失敗したら cp932 で読む」という方法がよく使われます。ここまでに作った 3 つのファイルで試します。

def read_text_auto(path):
    for enc in ["utf-8-sig", "cp932"]:
        try:
            with open(path, encoding=enc) as f:
                return f.read(), enc
        except UnicodeDecodeError:
            pass
    raise ValueError(f"文字コードを判定できません: {path}")

for name in ["utf8.txt", "score.csv", "sjis.txt"]:
    text, enc = read_text_auto(name)
    print(name, enc, repr(text))
utf8.txt utf-8-sig '売上データ\n'
score.csv utf-8-sig '名前,点数\n佐藤,80\n'
sjis.txt cp932 '売上データ\n'

UTF-8 を先に試すのがポイントです。先ほど見たとおり、UTF-8 のファイルは cp932 でもエラーなしで(文字化けして)読めてしまうことがあるからです。ただし確実な判定方法ではなく、「UTF-8 か Shift_JIS のどちらか」と分かっているときの簡易な方法です。

Shift_JIS のファイルを UTF-8 に変換する

読むときと書くときで encoding を変えれば、文字コードの変換になります。

# Shift_JIS のファイルを UTF-8 に変換して保存する
with open("sjis.txt", encoding="cp932") as src:
    text = src.read()
with open("sjis_to_utf8.txt", "w", encoding="utf-8") as dst:
    dst.write(text)

変換後のファイルは、「売」が E5 A3 B2 の UTF-8 になっていました。逆に cp932 へ変換するときは、絵文字など cp932 にない文字があると UnicodeEncodeError になります。"OK😀\n" を cp932 で書き込もうとしたところ、'cp932' codec can't encode character というエラーになり、ファイルは 0 バイト(OK の部分も書かれない)のまま残りました。

変換する前に、文章の中に Shift_JIS で表せない文字がないかを調べておくと安心です。文字数・バイト数カウントに文章を貼ると、Shift_JIS で表せない文字が何行目の何文字目にあるかを表示できます。

改行コード(\r\n)の扱い:newline 引数

ここまでの出力で、書き込んだのは \n なのに、ファイルの中身は \r\n になっていたことに気づいたでしょうか。テキストモードの Python は、改行を次のように自動で変換しています。

  • 書き込み:\n を OS の標準の改行(Windows は \r\n、Linux・macOS は \n)に変えて書く
  • 読み込み:\r\n・\r・\n のどれも \n にそろえて渡す

この変換は newline 引数で変えられます。書き込みで試した結果です。

# 書き込み:newline の指定で、ファイルに入る改行が変わる
for nl in [None, "", "\n", "\r\n"]:
    with open("nl.txt", "w", encoding="utf-8", newline=nl) as f:
        f.write("a\nb\n")
    with open("nl.txt", "rb") as f:
        print(repr(nl), f.read())
None b'a\r\nb\r\n'
'' b'a\nb\n'
'\n' b'a\nb\n'
'\r\n' b'a\r\nb\r\n'

Linux 用のシェルスクリプトなど、改行を LF(\n)にしたいファイルを Windows で作るときは、newline="\n" を指定します。

読み込みでは、newline="" にすると変換せずに元の改行のまま受け取れます。a\r\nb\r\n というバイトのファイルを読んだところ、既定では 'a\nb\n'、newline="" では 'a\r\nb\r\n' になりました。このとき line.rstrip("\n") で改行を消そうとすると 'a\r' のように \r が残るので、rstrip("\r\n") を使いましょう。

なお、csv モジュールを使うときは newline=”” を指定するよう、公式ドキュメントに書かれています。この PC で newline を指定せずに csv.writer で 2 行書いたところ、行末が \r\r\n になり、読み直すと行の間に空の行が入りました。改行コードの種類は「改行コードCRLFとLFの違い」で解説しています。

画像などはバイナリモード(rb・wb)で扱う

画像・PDF・zip などのテキストではないファイルや、文字コードを変換せずにそのまま扱いたいときは、モードに b を付けます。バイナリモードでは文字列(str)ではなくバイト列(bytes)を読み書きし、改行の変換も行いません。

with open("sjis.txt", "rb") as f:
    data = f.read()
print(type(data), len(data))
print(data.decode("cp932"))
<class 'bytes'> 12
売上データ

改行も変換されないので、「売上データ」5 文字×2 バイトと \r\n の 2 バイトで 12 バイトです。bytes は decode("文字コード") で文字列に変えられます。バイナリモードに encoding を付けると ValueError: binary mode doesn't take an encoding argument、wb で開いたファイルに文字列を書くと TypeError: a bytes-like object is required, not 'str' になります。

pathlib の read_text・write_text で短く書く

ファイル全体をまとめて読み書きするだけなら、標準ライブラリの pathlib を使うと 1 行で書けます。ここでも encoding は必ず指定します。

from pathlib import Path

p = Path("output") / "result.txt"
p.parent.mkdir(exist_ok=True)

n = p.write_text("合計: 120件\n", encoding="utf-8")
print(n)
print(repr(p.read_text(encoding="utf-8")))
print(p.read_bytes())
print(p.exists(), p.stat().st_size)
9
'合計: 120件\n'
b'\xe5\x90\x88\xe8\xa8\x88: 120\xe4\xbb\xb6\r\n'
True 16

/ でフォルダー名とファイル名をつなげられ、OS によるパスの区切り(\ と /)の違いを気にせずに済みます。write_text() の戻り値 9 は書き込んだ文字数で、ファイルサイズ(16 バイト)とは違う点に注意してください。write_text は既存のファイルを上書きし、改行は open() の w モードと同じく \r\n に変換されます(Python 3.10 以降は newline="\n" も指定できます)。read_text はファイル全体を一度に読み込むので、数百 MB のログのような大きなファイルは、open() と for 文で 1 行ずつ読む方が向いています。

よくあるエラーと直し方の早見表

エラー・症状よくある原因直し方
‘cp932’ codec can’t decode byte …UTF-8 のファイルを encoding なしで読んだ(Windows)encoding=”utf-8″(BOM があり得るなら utf-8-sig)
‘utf-8’ codec can’t decode byte …Shift_JIS のファイルを UTF-8 で読んだencoding=”cp932″
‘cp932’ codec can’t encode character …絵文字などを cp932 で書こうとしたUTF-8 で書く。cp932 が必要なら文字を置き換える
先頭のキーが ‘\ufeff名前’ になるBOM 付きを utf-8 で読んだencoding=”utf-8-sig”
縺・繧 だらけの文字化けUTF-8 を cp932 で読んだencoding=”utf-8″
CSV の行の間に空行が入るcsv モジュールで newline を指定していないnewline=””
ファイルが空になったw モードで開いた追記は a、上書き防止は x

まとめ

  • ファイルは with open(...) で開き、encoding は必ず指定する
  • 省略すると日本語版 Windows(Python 3.12)では cp932。基本は utf-8、BOM 付きや Excel 向けの CSV は utf-8-sig、Windows の Shift_JIS は cp932
  • UnicodeDecodeError は指定違い。errors は調査用。LF で書くときや csv では newline を指定する

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました