Pandas to_csvでCSV出力時のエンコード問題と解決策：日本語データも安心
2025-05-31
基本的な使い方
最も基本的な使い方は、DataFrameオブジェクトに対して .to_csv() メソッドを呼び出し、保存したいファイルのパスを指定することです。
import pandas as pd
# 例としてDataFrameを作成
data = {'名前': ['Alice', 'Bob', 'Charlie'],
'年齢': [25, 30, 28],
'都市': ['東京', '大阪', '名古屋']}
df = pd.DataFrame(data)
# 'output.csv' という名前のファイルに保存
df.to_csv('output.csv')
このコードを実行すると、DataFrame df の内容が output.csv というファイルに保存されます。ファイルを開くと、カンマで区切られたデータが表示されます。
主要な引数
to_csv() メソッドには、CSVファイルの出力形式を細かく制御するための多くの引数があります。主なものをいくつか紹介します。
compression: 出力ファイルを圧縮する形式を指定します。'gzip','bz2','zip','xz'などが指定できます。ファイル名が.gz,.bz2,.zip,.xzで終わる場合は自動的に推測されます。mode: ファイルを開くモードを指定します。デフォルトは'w'(書き込み) です。追記したい場合は'a'を指定できます。index_label: インデックス列の名前を指定します。index=Trueの場合に有効です。quoting: 文字列のクォーティング規則を指定します。例えば、常に文字列をダブルクォーテーションで囲むように設定できます。na_rep: 欠損値 (NaN) をCSVファイル内でどのように表現するかを指定します。デフォルトは空の文字列です。例えば'NULL'などと指定できます。columns: CSVファイルに出力する列の名前のリストを指定します。DataFrameの一部の列だけを保存したい場合に便利です。header: DataFrameのヘッダー（列名）をCSVファイルに出力するかどうかを指定します。デフォルトはTrueでヘッダーが出力されます。ヘッダーを出力したくない場合はFalseを指定します。index: DataFrameのインデックスをCSVファイルに出力するかどうかを指定します。デフォルトはTrueでインデックスが出力されます。インデックスを出力したくない場合はFalseを指定します。sep: CSVファイル内の各フィールドを区切る文字を指定します。デフォルトは','(カンマ) ですが、タブ区切りにしたい場合は'\t'を指定できます。path_or_buf: 保存先のファイルパス（文字列）またはファイルライクオブジェクトを指定します。上記例の'output.csv'がこれにあたります。
例
インデックスを出力せず、セミコロン区切りで、欠損値を 'N/A' として、UTF-8エンコーディングで保存する場合：
import pandas as pd
import numpy as np
data = {'名前': ['Alice', 'Bob', None],
'年齢': [25, 30, 28],
'都市': ['東京', '大阪', '名古屋']}
df = pd.DataFrame(data)
df.to_csv('output_custom.csv', index=False, sep=';', na_rep='N/A', encoding='utf-8')
FileNotFoundError: [Errno 2] No such file or directory: (ファイルが見つかりません)
- トラブルシューティング
- 指定したパスが正しいか、タイプミスがないかを確認してください。
- 保存先のディレクトリが存在することを確認してください。存在しない場合は、事前に
os.makedirs()などでディレクトリを作成する必要があります。 - 相対パスを使用している場合は、現在の作業ディレクトリが意図した場所にあるか確認してください。
- 原因
指定したpath_or_bufのパスが存在しないディレクトリを示している場合に発生します。
PermissionError: [Errno 13] Permission denied: (許可がありません)
- トラブルシューティング
- ファイルを保存しようとしているディレクトリに対する書き込み権限があるか確認してください。
- 他のプログラムが同じファイルを使用中で、書き込みロックがかかっていないか確認してください。
- 管理者権限で実行する必要がある場合は、そのようにプログラムを実行してみてください。
- 原因
指定したパスへの書き込み権限がない場合に発生します。
UnicodeEncodeError: '...' codec can't encode character '...' in position ...: (Unicodeエンコードエラー)
CSVファイルの形式が意図したものと異なる (区切り文字、インデックス、ヘッダーなど)
- トラブルシューティング
sep引数が、期待する区切り文字（デフォルトはカンマ,）になっているか確認してください。タブ区切りにしたい場合はsep='\t'を指定します。- インデックスを出力したくない場合は
index=Falseを指定してください。 - ヘッダー（列名）を出力したくない場合は
header=Falseを指定してください。 - 出力する列を限定したい場合は
columns引数に列名のリストを指定してください。
- 原因
sep,index,headerなどの引数の設定が意図したCSVファイルの形式と異なっている場合に発生します。
欠損値 (NaN) の扱いの問題
- トラブルシューティング
na_rep引数を使用して、欠損値を表す文字列を指定してください。例えば、na_rep='NULL'やna_rep='NaN'などと指定できます。df.to_csv('output_na.csv', na_rep='N/A')
- 原因
DataFrameに欠損値が含まれており、その表現がデフォルトの空文字列で意図しない形式になっている場合に発生します。
ファイルが正しく追記されない (追記モード mode='a')
- トラブルシューティング
- 追記モードでヘッダーを重複して出力したくない場合は、最初の書き込み時のみ
header=Trueとし、以降の追記ではheader=Falseとする必要があります。ただし、これを自動で行う機能はないため、自分で制御する必要があります。 - 一般的には、追記処理は慎重に行う必要があり、ファイル構造が壊れないように注意が必要です。
- 追記モードでヘッダーを重複して出力したくない場合は、最初の書き込み時のみ
- 原因
追記モード (mode='a') を使用している場合に、ヘッダーが重複して出力されたり、意図したように追記されないことがあります。
- トラブルシューティング
- gzip圧縮を使用する場合は
gzipライブラリ、bz2圧縮の場合はbz2ライブラリ、zip圧縮の場合はzipfileライブラリ、xz圧縮の場合はlzmaライブラリがインストールされているか確認してください。 compression引数に指定する文字列 ('gzip','bz2','zip','xz') が正しいか確認してください。- ファイル名が
.gz,.bz2,.zip,.xzで終わる場合は、compression='infer'を指定することで自動的に圧縮形式が推測されます。
- gzip圧縮を使用する場合は
- 原因
compression引数を使用している場合に、必要なライブラリがインストールされていなかったり、指定した形式が正しくなかったりする場合があります。
基本的な保存
import pandas as pd
# サンプルデータフレームの作成
data = {'名前': ['一郎', '二郎', '三郎'],
'年齢': [20, 25, 30],
'都市': ['東京', '大阪', '名古屋']}
df = pd.DataFrame(data)
# デフォルトの設定でCSVファイルに保存 (indexも出力される)
df.to_csv('basic_output.csv')
print("basic_output.csv を保存しました。")
この例では、DataFrame df の内容を basic_output.csv というファイルに保存します。特に引数を指定しない場合、インデックスもCSVファイルに出力されます。
インデックスを出力しない
import pandas as pd
data = {'名前': ['一郎', '二郎', '三郎'],
'年齢': [20, 25, 30],
'都市': ['東京', '大阪', '名古屋']}
df = pd.DataFrame(data)
# index=False を指定してインデックスを出力しない
df.to_csv('no_index_output.csv', index=False)
print("no_index_output.csv (インデックスなし) を保存しました。")
index=False を指定することで、CSVファイルにDataFrameのインデックスが出力されなくなります。
区切り文字を変更する (タブ区切り)
import pandas as pd
data = {'名前': ['一郎', '二郎', '三郎'],
'年齢': [20, 25, 30],
'都市': ['東京', '大阪', '名古屋']}
df = pd.DataFrame(data)
# 区切り文字をタブに変更
df.to_csv('tab_separated.csv', sep='\t', index=False)
print("tab_separated.csv (タブ区切り) を保存しました。")
sep='\t' を指定することで、CSVファイルの区切り文字がカンマからタブになります。
ヘッダーを出力しない
import pandas as pd
data = {'名前': ['一郎', '二郎', '三郎'],
'年齢': [20, 25, 30],
'都市': ['東京', '大阪', '名古屋']}
df = pd.DataFrame(data)
# header=False を指定してヘッダーを出力しない
df.to_csv('no_header.csv', header=False, index=False)
print("no_header.csv (ヘッダーなし) を保存しました。")
header=False を指定することで、CSVファイルにDataFrameのヘッダー（列名）が出力されなくなります。
特定の列のみを保存する
import pandas as pd
data = {'名前': ['一郎', '二郎', '三郎'],
'年齢': [20, 25, 30],
'都市': ['東京', '大阪', '名古屋'],
'職業': ['エンジニア', 'デザイナー', '営業']}
df = pd.DataFrame(data)
# 保存する列を指定
columns_to_save = ['名前', '年齢']
df.to_csv('selected_columns.csv', columns=columns_to_save, index=False)
print("selected_columns.csv (選択された列のみ) を保存しました。")
columns 引数に保存したい列名のリストを指定することで、DataFrameの一部の列だけをCSVファイルに保存できます。
欠損値の表現を変更する
import pandas as pd
import numpy as np
data = {'名前': ['一郎', '二郎', np.nan],
'年齢': [20, np.nan, 30],
'都市': [np.nan, '大阪', '名古屋']}
df = pd.DataFrame(data)
# 欠損値を 'NULL' として保存
df.to_csv('na_replaced.csv', na_rep='NULL', index=False)
print("na_replaced.csv (欠損値を 'NULL' で表現) を保存しました。")
na_rep 引数に文字列を指定することで、DataFrame内の欠損値 (NaN) をCSVファイル内でその文字列で表現できます。
エンコーディングを指定する (UTF-8)
import pandas as pd
data = {'名前': ['一郎', '二郎', '三郎'],
'年齢': [20, 25, 30],
'都市': ['東京', '大阪', '名古屋']}
df = pd.DataFrame(data)
# エンコーディングを UTF-8 で指定
df.to_csv('utf8_encoded.csv', encoding='utf-8', index=False)
print("utf8_encoded.csv (UTF-8 エンコーディング) を保存しました。")
エンコーディングを指定する (Shift-JIS)
import pandas as pd
data = {'名前': ['一郎', '二郎', '三郎'],
'年齢': [20, 25, 30],
'都市': ['東京', '大阪', '名古屋']}
df = pd.DataFrame(data)
# エンコーディングを Shift-JIS で指定
df.to_csv('sjis_encoded.csv', encoding='shift-jis', index=False)
print("sjis_encoded.csv (Shift-JIS エンコーディング) を保存しました。")
特定の環境に合わせて、encoding='shift-jis' などを指定することもできます。
インデックスに名前をつける
import pandas as pd
data = {'名前': ['一郎', '二郎', '三郎'],
'年齢': [20, 25, 30],
'都市': ['東京', '大阪', '名古屋']}
df = pd.DataFrame(data)
# インデックスに名前をつける
df.index.name = 'ID'
df.to_csv('index_label.csv', index_label='ID')
print("index_label.csv (インデックスに 'ID' というラベル) を保存しました。")
index_label 引数を使用すると、出力されるインデックス列に名前をつけることができます。
gzipで圧縮して保存する
import pandas as pd
data = {'名前': ['一郎', '二郎', '三郎'],
'年齢': [20, 25, 30],
'都市': ['東京', '大阪', '名古屋']}
df = pd.DataFrame(data)
# gzipで圧縮して保存
df.to_csv('compressed.csv.gz', compression='gzip', index=False)
print("compressed.csv.gz (gzip圧縮) を保存しました。")
compression='gzip' を指定することで、CSVファイルをgzip形式で圧縮して保存できます。ファイル名が .gz で終わる場合、compression='infer' で自動的にgzip圧縮が適用されます。
他のファイル形式への出力
-
DataFrame.to_hdf(path_or_buf, key, mode='a', complevel=None, complib=None, append=False, format='fixed', **kwargs)
- DataFrameをHDF5形式のファイルに保存します。
- 大規模なデータセットの保存や、高速な読み書きに適しています。
- 複数のDataFrameを同じファイルに保存したり、部分的に読み込んだりすることも可能です。
import pandas as pd data = {'名前': ['一郎', '二郎', '三郎'], '年齢': [20, 25, 30]} df = pd.DataFrame(data) df.to_hdf('output.h5', key='data', mode='w') print("output.h5 を保存しました。") # 後で読み込む場合 loaded_df = pd.read_hdf('output.h5', key='data') print(loaded_df) -
DataFrame.to_pickle(path, compression='infer', protocol=5, storage_options=None)
- DataFrameをpickle形式のバイナリファイルにシリアライズして保存します。
- pickle形式はpandasのDataFrameの構造をそのまま保存できるため、読み込みが高速です。
- 異なるPythonプロセス間や、後で同じDataFrameを読み込みたい場合に便利です。
import pandas as pd data = {'名前': ['一郎', '二郎', '三郎'], '年齢': [20, 25, 30]} df = pd.DataFrame(data) df.to_pickle('output.pkl') print("output.pkl を保存しました。") # 後で読み込む場合 loaded_df = pd.read_pickle('output.pkl') print(loaded_df) -
DataFrame.to_json(path_or_buf=None, orient=None, date_format=None, double_precision=10, force_ascii=True, date_unit='ms', default_handler=None, lines=False, compression='infer', index=True, indent=None, storage_options=None)
- DataFrameの内容をJSON形式のファイルまたは文字列に出力します。
orient引数でJSONの構造（例:'records','index','columns','values'など）を制御できます。- WebアプリケーションやAPIとの連携でよく使用されます。
import pandas as pd data = {'名前': ['一郎', '二郎', '三郎'], '年齢': [20, 25, 30]} df = pd.DataFrame(data) df.to_json('output.json', orient='records', force_ascii=False, indent=4) print("output.json を保存しました。") -
- DataFrameの内容をExcelファイル (
.xlsx) に出力します。複数のシートへの書き込みや、書式設定など、CSVよりも高度な出力が可能です。 sheet_nameでシート名を指定できます。index,header,columnsなどの引数はto_csvと同様の役割を果たします。engineで使用するExcel書き込みエンジン（openpyxlやxlsxwriterなど）を指定できます。
import pandas as pd data = {'名前': ['一郎', '二郎', '三郎'], '年齢': [20, 25, 30]} df = pd.DataFrame(data) df.to_excel('output.xlsx', sheet_name='名簿', index=False) print("output.xlsx を保存しました。") - DataFrameの内容をExcelファイル (
他のデータストアへの出力
-
データベースへの出力
- pandasはSQLAlchemyなどのライブラリと連携して、DataFrameの内容をSQLデータベースのテーブルに書き込むことができます。
DataFrame.to_sql(name, con, schema=None, if_exists='fail', index=True, index_label=None, chunksize=None, dtype=None, method=None)を使用します。con引数にはSQLAlchemyのエンジンやデータベース接続オブジェクトを指定します。
import pandas as pd from sqlalchemy import create_engine data = {'名前': ['一郎', '二郎', '三郎'], '年齢': [20, 25, 30]} df = pd.DataFrame(data) # SQLiteのインメモリデータベースを作成 engine = create_engine('sqlite:///:memory:') # DataFrameをSQLテーブルに書き込む df.to_sql('users', engine, if_exists='replace', index=False) print("DataFrame を SQL テーブル 'users' に保存しました。") # 確認のために読み込む loaded_df = pd.read_sql('SELECT * FROM users', engine) print(loaded_df)