PythonでCSVを読み書きする方法｜文字コード・列・集計の確認手順

※本記事にはPRを含む場合があります。

こんにちは。『脱会社員』脱サラを応援し続けるブログ、運営者の『なかびー』です。

PythonでCSVを扱うときは、読み込むコードだけでなく、文字コード、列名、値の意味、出力先を先に確認することが大切です。ファイルを開けても、先頭の0が消えた、金額を文字のまま扱った、不正な行を飛ばして合計が変わったという問題が残ることがあります。小さな仮のデータで、読み取りから集計と書き出し後の照合までを一周してみましょう。

この記事では、標準ライブラリのcsvを使い、架空の文房具の明細を読み書きします。追加ライブラリを入れず、reader、DictReader、writer、DictWriterの違いを学ぶ入門です。Pythonの変数、for文、with文を少し学んだ方を想定しています。実際の顧客情報や売上データは使わず、練習用のコピーで進めてください。

2026年10月3日にPython公式ドキュメントを確認しました。サンプルの数量・価格・合計は説明用の仮定で、筆者の実績ではありません。図版も説明用の生成イメージです。コードは小さな信頼済みの練習データ向けで、あらゆる外部CSVや業務システムへそのまま適用できる完成品ではありません。

PythonでCSVを扱う準備｜文字コード・区切り・原本を確認する

CSVは表計算ファイルと同じではない

CSVは、区切り文字などの規則を使って行と列の値を表すテキスト形式です。表計算ソフトのブックにある色、数式、複数シート、セルの表示形式がそのまま保存されるものではありません。見た目が表として開けても、中身は文字の並びです。どの列を数値として扱うか、日付はどの形式かといった意味は、読み取る側で確認する必要があります。

拡張子が.csvでも、文字コード、区切り、引用符、改行、ヘッダーの有無が同じとは限りません。受け取ったデータの仕様や、書き出したシステムの案内を確認してください。最初の数行だけを見て全体の形式を断定せず、カンマや改行を含む値がないかも考えます。単純な文字列の分割では扱えないケースがあるため、csvモジュールを使う意味があります。

Python公式のcsvモジュール説明では、表形式の読み書きと、アプリケーションごとにある形式の違いが説明されています。CSVを読むことと、値が業務上正しいことを確認することは別です。まず形式を読み取り、その後に列と値を検証する順番を意識しましょう。

原本を残し、入力と出力の場所を分ける

作業前に原本を保存し、練習用のコピーを別フォルダーへ置きます。読み取るファイルと書き出すファイルに同じ名前を使わないようにします。最初から原本へ上書きすると、変換が間違っていた場合に戻せなくなる可能性があります。入力はsample.csv、出力はresult.csvなど、役割が分かる名前から始めると管理しやすくなります。

相対パスは、スクリプトの場所ではなく実行時の作業フォルダーを基準に解決される場面があります。ファイルが見つからないとき、名前だけが間違っているとは限りません。どこから実行しているかを確認し、必要ならPathで明示した場所を使います。pathlibの公式ドキュメントも参考に、文字列の連結だけでパスを作らない方法を覚えると整理しやすくなります。

共有フォルダーや同期中の場所を使う場合は、別の人や別の処理が同時にファイルを更新していないかも考えます。毎回同じ名前で届くデータなら、取得した日時と元ファイルの版を記録します。練習では一つのローカルフォルダーへコピーし、誰も更新しない状態で読み書きを試す方が、プログラム自体の挙動を確認しやすくなります。

文字コードは根拠を持って指定する

Pythonでテキストを開くときは、入力ファイルに合うencodingを指定します。UTF-8のCSV、BOM付きUTF-8のCSV、日本語の従来環境で作られたCSVなどで扱いが変わります。ファイルの仕様が分かるならそれを優先し、エラーが出るたびに当てずっぽうで文字コードを変えないようにしましょう。読めたように見えても、一部の文字だけ崩れる場合があります。

utf-8-sigは、先頭にUTF-8のBOMがある入力を扱うときの選択肢です。BOMのないUTF-8も読み取れますが、これであらゆる日本語CSVが読めるわけではありません。cp932などを使う必要があるファイルは、その形式である根拠を確認して指定します。文字コードと区切りの問題を混同せず、まず文字として正しく読めることを確かめてください。

errors=’ignore’などで読めない文字を黙って捨てる方法は、内容の欠落に気づけなくなるため、原因調査の最初の対応には向きません。氏名、商品名、識別子の一文字が消えると別の値になる可能性があります。原本を残し、発生箇所と出力元の仕様を確認して対応します。openの公式説明で、文字コード、エラー処理、モードの意味を確認しましょう。

※表は横にスクロールできます。

newlineはcsvモジュールへ改行処理を任せる

csvモジュールでファイルを読み書きする場合、公式例にあるnewline=”の指定を確認してください。CSV内部の改行処理をモジュールへ任せるために使います。特に書き出しで余分な空行が出るなどの問題を避けるため、encodingと合わせて明示する習慣を付けるとよいでしょう。通常のテキスト読み書きと同じ感覚で省略しないようにします。

値の中に改行を含むCSVでは、テキストの物理的な一行と、一件のレコードが一致しない場合があります。行数を数えるコマンドの結果を、そのままデータ件数と考えないようにしてください。後の検証では、csvで読み取ったレコード数と、入力仕様から期待する件数を照合します。形式を理解することが、正しい集計の前提になります。

CSVを読む｜readerとDictReaderで行と列を理解する

まず小さなサンプルを用意する

次の内容をUTF-8のsample.csvとして保存します。record_idは一件の明細を識別する文字列、quantityは個数、unit_priceは円単位の整数という練習上の仕様にします。品名の「ノート,青」にはカンマが含まれるため、引用符で囲んでいます。価格や数量は架空です。実際の業務では、返品や小数、税など別のルールが必要になる場合があります。

record_id,item,quantity,unit_price
0001,"ノート,青",2,300
0002,ペン,3,120
0003,メモ帳,1,250

このサンプルでは、データは三件です。各明細の数量と単価を掛けると600、360、250で、合計は1210になります。後でプログラムの出力をこの手計算と比べます。大きなデータでいきなり試すより、正解を自分で確認できる小さなデータを用意すると、読み取りや計算の誤りを見つけやすくなります。

空のファイル、ヘッダーだけのファイル、列が一つ不足したファイルも、後で別名のテスト用として用意できます。最初から正常データへ混ぜず、条件ごとに分けて試してください。どの入力で何が起きるかを一つずつ確認すると、プログラムの仕様を説明しやすくなります。原本の正常サンプルは残しておきましょう。

readerは位置で値を取り出す

csv.readerで読むと、各行の値をリストとして扱えます。先頭がヘッダーなら、nextで一行を取り出して内容を確認し、その後の行を処理する方法があります。列数と順番が固定された小さな形式では、位置による処理が分かりやすい場合があります。ただし、途中で列が増えたり並びが変わったりすると、意図しない値を読んでしまう可能性があります。

import csv
from pathlib import Path
source = Path('sample.csv')
with source.open('r', encoding='utf-8-sig', newline='') as file:
    reader = csv.reader(file)
    header = next(reader, None)
    print('列名:', header)
    for row in reader:
        print('列数:', len(row), '値:', row)

品名のカンマが一つの値として扱われ、四列で読めることを確認します。line.split(‘,’)のように単純分割すると、引用符の中のカンマまで区切りとして扱い、列が増えてしまいます。CSV用のパーサーを使えば、引用符などの規則を理解して読み取れます。自作の分割処理を増やす前に、標準モジュールで扱える範囲を確認しましょう。

上のコードは読み取った内容を確認するための練習です。実データでは、すべての行を画面やログへ出すと個人情報などが残る可能性があります。件数や列名だけを表示する、問題のある列とレコード番号だけを記録するなど、必要な情報へ絞ります。デバッグの便利さと、データをむやみに複製しないことを両立させてください。

DictReaderは列名で値を読む

csv.DictReaderでは、通常は先頭行を列名として使い、各レコードを辞書の形で扱えます。row[‘item’]のように意味の分かる名前で取り出せるため、位置の数字だけで処理するより読みやすくなる場面があります。列順が変わっても、名前が正しく保たれていれば対応しやすいことが利点です。ただし、列名の誤りや重複は事前に検証する必要があります。

import csv
with open('sample.csv', encoding='utf-8-sig', newline='') as file:
    reader = csv.DictReader(file)
    print('ヘッダー:', reader.fieldnames)
    for row in reader:
        print(row['record_id'], row['item'], row['quantity'])

列名に余分な空白がある、BOMが残っている、綴りが違うといった場合、期待したキーで取り出せないことがあります。KeyErrorが出たら、存在しない列を作って埋める前に、実際のfieldnamesを確認します。自動で列名を変更する運用にするなら、どの変更を許すかを仕様として決め、原本の違いが分かる記録を残すことが大切です。

列名が重複していると、辞書のキーとして一意に扱えず、値の扱いが期待どおりにならない原因になります。列名の数と重複、必要な列が揃っていることを読み込みの初めに確認します。ヘッダーがないデータへDictReaderをそのまま使うと、最初のデータ行を列名として扱ってしまう可能性もあるため、入力仕様を先に確認してください。

※表は横にスクロールできます。

読めることと列が正しいことを分ける

DictReaderは、行の列数がヘッダーと違う場合も、すべてが即座にエラーになるとは限りません。余分な値や不足した値がどのように扱われるかを理解し、必要な検証を入れます。サンプルの完成例では、余分な列や不足を検知したら停止します。黙って不足値を空欄へ置き換えるより、入力の問題を先に直す方針です。

区切りを推測する機能もありますが、推測は必ず正しいとは限りません。仕様が分かっているデータなら、delimiterなどを明示する方が再現しやすくなります。初めて受け取った形式を調べる場合も、推測結果をそのまま業務処理へ渡さず、列数と代表的な値を確認します。読み取りの段階で違和感を見つけることが、集計結果の誤りを減らします。

値を整えて集計する｜型変換・欠損・エラーを分ける

数字に見える値も、まず文字列として扱う

csvで読み取った値は、通常は文字列です。quantityの’2’とunit_priceの’300’を数値として掛けたいなら、用途に合う型へ変換します。文字列をそのまま足すと連結になり、期待する計算とは違う結果になる場合があります。数値化が必要な列と、文字のまま保つ列を先に決めましょう。

record_idの0001は、計算する数ではなく識別子です。intへ変換すると1になり、先頭の0が失われます。電話番号や商品コードなども同じように、見た目が数字だから数値と判断しないことが大切です。後で桁数を戻せばよいと考えても、元の表記が不明になる場合があります。値の意味を基準に型を選んでください。

quantity = int(row['quantity'])
unit_price = int(row['unit_price'])
line_total = quantity * unit_price
record_id = row['record_id']

この断片は、値が正しい整数であることをまだ検証していません。空欄、小数、文字が混ざると変換できない場合があります。また、負の数量を許すか、単価が0でもよいかはデータの仕様です。練習では数量1以上、単価0以上の整数と決めます。返品や割引を扱う業務へ、そのまま同じ条件を当てはめないようにします。

空欄と0は同じ意味にしない

空欄は未入力や不明、0は値がゼロと確認された状態を表す場合があります。欠損をすべて0へ変えると、合計が計算できても意味が変わる可能性があります。どの列で空欄を許すか、許す場合はどう扱うかを決めます。数量がない明細を0件とみなしてよいかは、プログラムの都合で判断しないでください。

前後の空白を取り除く処理も、目的に合う範囲で行います。数量の前後の空白は不要として取り除ける場合がありますが、自由記述や識別子の中の空白まで削ると別の値になる可能性があります。正規化した結果を使うなら、どの列へ何をしたか説明できるようにします。便利そうな文字変換を全列へ一律に適用しないことが大切です。

集計時に不正な行を飛ばす方針にする場合は、除外した件数と理由を必ず残します。エラーを隠して最後まで進めると、件数不足に気づかず結果を使う危険があります。この記事の完成例は、小さなデータを確実に確認するため、一件でも不正があれば出力前に停止します。継続処理に変えるときは、結果が完全な集計かどうか分かる設計が必要です。

整数の金額という仮定を明示する

サンプルでは単価を円単位の整数として扱い、数量との積を整数で計算します。これは入門のための仮定です。小数の金額、税計算、通貨換算、丸め規則などが必要な場合は、仕様に合う型と丸め方を決めます。浮動小数点数の計算をそのまま金額の正確な処理へ使えると考えないようにしましょう。

合計を作る前に、まず一行の計算を手で確認します。ノートの例なら2×300で600です。その後、三行の合計1210を確認します。最初から全体の合計だけを見ると、二つの誤りが相殺されて気づけない場合があります。件数、一行の値、部分合計、全体合計という順に比べると、どこで違いが生まれたかを探しやすくなります。

※表は横にスクロールできます。

集計結果には件数も添える

合計だけが出ても、何件から計算したか分からなければ判断しにくくなります。入力件数、処理した件数、除外件数があるならその数も記録します。今回の例では三件すべてを検証し、三件の出力と合計1210になることを確認します。処理が停止した場合は成功として扱わず、出力が作られなかったことまで確認します。

同じファイルを二回処理したときの結果も考えます。追記モードを不用意に使うと、同じ明細が重複して出力される場合があります。出力ファイルの扱いを決め、再実行が上書きなのか、別名なのか、追記なのかを明確にします。初心者の練習では、既存ファイルがあれば止まる方法を使うと、誤った上書きを避けやすくなります。

CSVを書き出す｜列順・改行・上書き防止の確認

writerとDictWriterを使い分ける

writerでは、リストなどの並びを一行として書き出せます。DictWriterでは、辞書の値を指定した列名の順番で出力できます。出力の列順は、後で読む人やシステムにとって重要な場合があります。辞書に値があるから大丈夫と考えず、fieldnamesで出す列を明示し、ヘッダーとデータが対応しているかを確認しましょう。

import csv
fields = ['record_id', 'item', 'quantity', 'unit_price', 'line_total']
with open('result.csv', 'x', encoding='utf-8-sig', newline='') as file:
    writer = csv.DictWriter(file, fieldnames=fields)
    writer.writeheader()
    writer.writerow({
        'record_id': '0001',
        'item': 'ノート,青',
        'quantity': 2,
        'unit_price': 300,
        'line_total': 600,
    })

‘x’は新規作成用で、同名のファイルが既にあれば失敗するモードです。’w’は既存の内容を置き換える可能性があるため、使う目的を理解して選びます。入力ファイルと出力ファイルを取り違えたときの影響が違います。書き込み先を画面へ表示して確認するなど、初めは慎重に進めてください。

csv.writerなどを使えば、カンマや引用符を含む値に必要な処理を行えます。値を自分でカンマでつなぎ、改行を足すだけの実装では、品名にカンマがある例で壊れてしまいます。標準モジュールへ形式の処理を任せ、プログラムでは値の意味と出力する列を管理する方が、役割を分けやすくなります。

読み取りから書き出しまでの完全例

次のコードをprocess_csv.pyとして、先ほどのsample.csvと同じフォルダーへ保存します。小さな練習データをすべて検証してから出力します。必要な列の不足・重複、列数の不一致、空欄、明細IDの重複、不正な数量や単価があれば停止します。result.csvが既にあれば上書きしません。実行は、使用している環境のPython起動コマンドに合わせてください。

import csv
from pathlib import Path
BASE = Path(__file__).resolve().parent
SOURCE = BASE / 'sample.csv'
TARGET = BASE / 'result.csv'
INPUT_FIELDS = ['record_id', 'item', 'quantity', 'unit_price']
OUTPUT_FIELDS = INPUT_FIELDS + ['line_total']
def parse_integer(value, field, minimum):
    text = value.strip()
    if not text:
        raise ValueError(f'{field}が空欄です')
    try:
        number = int(text)
    except ValueError as error:
        raise ValueError(f'{field}は整数で指定してください') from error
    if number < minimum:
        raise ValueError(f'{field}は{minimum}以上で指定してください')
    return number
def read_records(path):
    records = []
    seen_ids = set()
    with path.open('r', encoding='utf-8-sig', newline='') as file:
        reader = csv.DictReader(file, strict=True)
        headers = reader.fieldnames
        if headers is None:
            raise ValueError('ファイルが空です')
        if len(headers) != len(set(headers)):
            raise ValueError('列名が重複しています')
        if set(headers) != set(INPUT_FIELDS):
            raise ValueError('入力列が仕様と一致しません')
        for record_number, row in enumerate(reader, start=1):
            try:
                if None in row or any(row[key] is None for key in INPUT_FIELDS):
                    raise ValueError('列数が一致しません')
                record_id = row['record_id'].strip()
                item = row['item'].strip()
                if not record_id or not item:
                    raise ValueError('明細IDと品名は必須です')
                if record_id in seen_ids:
                    raise ValueError('明細IDが重複しています')
                quantity = parse_integer(row['quantity'], '数量', 1)
                unit_price = parse_integer(row['unit_price'], '単価', 0)
                records.append({
                    'record_id': record_id,
                    'item': item,
                    'quantity': quantity,
                    'unit_price': unit_price,
                    'line_total': quantity * unit_price,
                })
                seen_ids.add(record_id)
            except ValueError as error:
                raise ValueError(f'データレコード{record_number}: {error}') from error
    if not records:
        raise ValueError('ヘッダー以外のデータがありません')
    return records
def write_records(path, records):
    with path.open('x', encoding='utf-8-sig', newline='') as file:
        writer = csv.DictWriter(file, fieldnames=OUTPUT_FIELDS)
        writer.writeheader()
        writer.writerows(records)
def main():
    records = read_records(SOURCE)
    total = sum(row['line_total'] for row in records)
    write_records(TARGET, records)
    print(f'出力件数: {len(records)}')
    print(f'合計: {total}')
    print(f'出力先: {TARGET}')
if __name__ == '__main__':
    try:
        main()
    except (OSError, UnicodeError, csv.Error, ValueError) as error:
        raise SystemExit(f'処理を中止しました: {error}')

ここで示すデータレコード番号は、ヘッダーを除いて読み取ったレコードの順番です。値の中に改行がある場合の物理的な行番号とは一致しないことがあります。問題を調べるときは、その違いを意識してください。空の行の扱いもパーサーの動作と関わるため、テキストの見た目の行数だけで件数を数えないようにします。

この例は全件をリストへ持つため、巨大なCSV向けの設計ではありません。大きなデータでは、順に処理する方法、二段階で検証する方法、一時出力と完成ファイルを分ける方法などを検討します。小さいサンプルのコードを、大容量へそのまま広げてよいとは限りません。まず正しい結果が出ることを確認し、必要な規模に合わせて設計を変えます。

出力先の文字コードも用途で決める

完成例はutf-8-sigで書き出していますが、すべての連携先に適する唯一の形式ではありません。受け取り側がUTF-8のBOMなしを求める場合や、別の文字コードを指定する場合もあります。出力仕様を確認し、読み取る側で正しく列名と文字を扱えるかを試します。ファイルの先頭へ付く情報も、受け取り方によって影響することがあります。

書き出したCSVを表計算ソフトで開く場合、文字コードだけでなく列の型推測にも注意します。識別子の先頭0が表示上消える、長い番号が別の表記になる、日付に変換されるなど、CSV自体とは別にアプリ側の取り込みが影響することがあります。必要ならインポート時に文字列として扱う設定を使い、元のテキストと比較してください。

CSVの引用符は数式実行の防止とは別

外部から受け取った文字列をCSVへ出し、表計算ソフトで開く場合には、セルの内容が数式として解釈されるリスクも考える必要があります。OWASPのCSV Injection説明では、未信頼の入力をCSVへ含める際の問題が示されています。CSVとして正しく引用符で囲めたことだけで、どの表計算ソフトでも安全に表示できると考えないようにします。

今回の完成例は、自分で用意した文房具の練習データを前提にしています。未信頼の自由入力を安全な表計算ファイルへ変換する処理は含みません。実務では、出力を機械処理に使うのか、人が表計算ソフトで見るのかを分け、受け取り先に合う対策と確認が必要です。対策によって元の値が変わる場合もあるため、万能な置換を全列へ黙って行う運用は避けましょう。

※表は横にスクロールできます。

不具合を切り分ける｜文字化け・列ずれ・集計結果の照合

エラー名から調べる段階を絞る

FileNotFoundErrorなどファイルに関する問題なら、パスと作業フォルダー、ファイル名を確認します。UnicodeDecodeErrorなら、文字コードと元のファイルの仕様を確認します。KeyErrorなら列名、ValueErrorなら数値変換や検証条件など、どの段階で止まったかを見ます。すべてを「CSVが壊れた」とまとめず、読む前、読む途中、値の変換、書き込みに分けると調査しやすくなります。

エラーを捕まえて何もせず続けるコードは、処理の失敗を見えなくする可能性があります。入門では、何が起きたか分かる形で停止し、原本へ戻って確認できる方が安全です。例外の内容を記録するときも、行全体や個人情報を無条件に出さず、必要な項目と位置へ絞ります。調査用ログが新しい情報漏えいの原因にならないようにしましょう。

文字化けと列ずれを混同しない

日本語だけが崩れるなら文字コードを疑い、すべてが一列に入るなら区切り文字の違いを確認します。一部の行だけ列数が増えるなら、引用符やカンマを含む値の扱い、元ファイルの書き出しを見ます。画面で見える症状を短く記録し、原因に合う設定だけを変えてください。複数の設定を同時に変えると、何が直したのか分からなくなります。

ヘッダーだけ読み取れない場合は、先頭のBOM、見えない空白、列名の違いなどを調べます。reprで値の表現を確認する方法も役立ちますが、表示する内容は練習データや必要な列名へ限ります。見えない文字があったとしても、業務上必要な文字かもしれないため、削除してよいかを入力仕様と照合してください。

手計算、件数、再読み込みを組み合わせる

完成例を正常サンプルで実行したら、出力件数3、合計1210になることを確認します。result.csvをcsvモジュールで読み直し、record_idの0001が文字として残り、品名のカンマが一つの列内にあり、line_totalが600、360、250になっているか見ます。画面へ合計が出たことだけで成功と判断せず、出力ファイルの内容まで照合してください。

再実行するとresult.csvが既にあるため停止するのが、この例の仕様です。結果を更新したいときは、確認済みの旧出力を別名で保管するか、新しい出力名を指定するなど、意図した方法を選びます。上書きを避けるための停止を不具合と考えて、意味を確認せず’w’へ変えないようにしましょう。処理の目的に合わせて出力の運用を決めることが大切です。

書き込みの途中でOSのエラーなどが起きた場合は、途中までのファイルが残る可能性があります。ファイルが存在することだけで完成したと判断せず、終了状態と件数を確認します。実務で確実な受け渡しが必要なら、一時ファイルへ出して検証後に完成名へ切り替えるなどの設計を検討します。小さな練習でも、未完成と完成を区別する考え方を覚えておくと役立ちます。

※表は横にスクロールできます。

本番データへ進む前に入力仕様を文章にする

CSV処理を仕事へ使うなら、列名、文字コード、区切り、必須項目、数値の範囲、日付の形式、重複の扱いを短く文書へ残します。出力元の仕様変更があったとき、以前と何が違うか比べられるようにします。コードだけに条件を埋め込むより、データを用意する人とも合意しやすくなります。分からない値を推測で補う前に確認できる窓口も決めておきましょう。

大きなデータへ進む場合は、必要なメモリー、処理時間、途中失敗、再実行、個人情報の管理も検討します。標準csvで順に処理する方法が合う場合も、表形式の分析に特化した別のライブラリが合う場合もあります。道具を増やす前に、何を集計し、どの条件を守り、結果をどう確認するかを明確にすると選びやすくなります。

Pythonで小さな自動処理を作り、質問しながら業務改善の学習を進めたい場合は、副業向けプログラミングスクールの料金と支援比較も参考になります。Web制作とデータ処理では学ぶ内容が異なるため、Pythonやファイル処理が教材の対象か、どこまで相談できるかを確認してください。短いスクリプトが動いたことだけで、実務の責任をすべて負えるとは限りません。

PythonのCSV処理は、原本を残し、形式と列を確認し、必要な値だけを型変換し、別ファイルへ出して照合する順番で学べます。まず三件の仮データで、正しい結果と意図した停止の両方を試してください。エラーを消すことより、何を受け入れ、何を止めたかを説明できることが、信頼できる処理へ進むための基礎になります。