今回は、PandasデータフレームをCSVファイルとして書き出す方法を紹介します。
Pandasバージョン
本記事は、Pandas2.2.3の情報を基に執筆しています。
import pandas as pd
print(pd.__version__)
>>
2.2.3pd.to_csv()
Excelの出力にはpd.to_csv()を用います。必須の引数として、出力するファイルのパスを拡張子付きで指定します。相対パスでも絶対パスでも問題ありません。
DataFrame.to_csv(path_or_buf=None, *, sep=’,’, na_rep=”, float_format=None, columns=None, header=True, index=True, index_label=None, mode=’w’, encoding=None, compression=’infer’, quoting=None, quotechar='”‘, lineterminator=None, chunksize=None, date_format=None, doublequote=True, escapechar=None, decimal=’.’, errors=’strict’, storage_options=None)
以下のような形式で指定します。
df.to_csv('output/out.csv') 引数
| 引数 | 必須 | 説明 |
|---|---|---|
| path_or_buf | 出力するファイルのパスまたはfile-likeのオブジェクト。指定しない場合、結果が文字列として返される。 | |
| sep | 出力するファイルの区切り文字を1文字で指定する。 デフォルトはカンマ（,）。 | |
| na_rep | 欠損値の表現。デフォルトは”。 | |
| float_format | 出力するfloat型のフォーマットを指定する。 | |
| columns | 出力するカラムをリスト形式で指定する。 | |
| header | Falseとした場合、ヘッダーを出力しない。 列名をリストで指定した場合、その列名をヘッダーとして出力される。 | |
| index | Falseとすると、インデックス（行名）を出力しない。 デフォルトはTrue。 | |
| index_label | インデックス列の列名をStringで指定する。 | |
| mode | ファイルを開く際のモードを指定する。‘w’, ‘x’, ‘a’から指定可能。 | |
| encoding | 出力するファイルの文字コードを指定する。 | |
| compression | 出力するファイルを圧縮ファイル（zip, tarなど）として出力する際に指定する。 | |
| quoting | 出力ファイルの引用符の取扱いを指定する。 デフォルトはcsv.QUOTE_MINIMAL。 | |
| quotechar | 出力ファイルの引用符として使用する文字を指定する。 デフォルトはダブルクォート（”）。 | |
| lineterminator | 行末を表す文字（1文字）を指定する。 | |
| chunksize | 一度に出力する行数を指定する。ループ処理と併用する。 | |
| date_format | 日付型データのフォーマットを指定する。 | |
| doublequote | quotecharで指定した文字が値に含まれる場合の処理を指定する。 | |
| escapechar | sep及びquotecharで指定した文字をエスケープする際に用いる文字（１文字）を指定する。 | |
| decimal | 小数点として用いる文字（１文字）を指定する。 デフォルトはピリオド（.）。 | |
| errors | ファイル作成時のエラーハンドリング。Python標準のopen()に準拠。 | |
| storage_options | S3などリモートのファイルへのアクセスに必要な情報を辞書形式で指定する。 |
ここからは、よく使う引数をいくつか紹介しよう。
基本引数
以下のようなデータフレームを用意し、出力を検証します。
import pandas as pd
df = pd.DataFrame({'name': ['Raphael', 'Donatello'],
'mask': ['red', None],
'number': [55110.0001, 12345.6789]})path_or_buf
ファイル名を指定することで、データフレームをCSVファイルとして出力します。パスを指定する際、出力先のフォルダが存在しない場合はエラーとなります。
事前にフォルダの存在チェックといったエラーハンドリングを推奨します。
df.to_csv('output/out.csv')StringIOといったバッファに出力することも可能です。
本記事の検証では、出力の確認をプログラムで行うため、バッファに出力する形式をとります。
import io
buffer = io.StringIO()
df.to_csv(buffer, index=False)
print(buffer.getvalue())
>>
name,mask,number
Raphael,red,55110.0001
Donatello,,12345.6789出力先を指定しない場合、文字列が返されます。
df.to_csv(index=False)
>>
'name,mask,number\r\nRaphael,red,55110.0001\r\nDonatello,,12345.6789\r\n'sep
値の区切り文字を指定します。デフォルトはダブルクォート（”）です。
以下は、区切り文字をセミコロン（;）に指定した例です。
buffer = io.StringIO()
df.to_csv('output/out.csv', sep=";")
print(buffer.getvalue())
>>
;name;mask;number
0;Raphael;red;55110.0001
1;Donatello;;12345.6789na_rep
欠損値データ（NoneやNA/NANなど）の表現を指定します。デフォルトはブランクとして出力されます。
以下では、欠損値データを”欠損値”という値で出力します。
buffer = io.StringIO()
df.to_csv(buffer, na_rep="欠損値")
print(buffer.getvalue())
>>
,name,mask,number
0,Raphael,red,55110.0001
1,Donatello,欠損値,12345.6789float_format
小数点の表記を指定します。例えば小数第２位まで出力する場合は”%.2f”を指定します。
buffer = io.StringIO()
df.to_csv(buffer, float_format="%.2f")
print(buffer.getvalue())
>>
,name,mask,number
0,Raphael,red,55110.00
1,Donatello,,12345.68columns
出力対象のカラムをカラム名のリスト形式で指定します。
buffer = io.StringIO()
df.to_csv(buffer, columns=["name", "number"])
print(buffer.getvalue())
>>
,name,number
0,Raphael,55110.0001
1,Donatello,12345.6789header
ヘッダーの出力有無を指定します。デフォルトはTrueです。
buffer = io.StringIO()
df.to_csv(buffer, header=False)
print(buffer.getvalue())
>>
0,Raphael,red,55110.0001
1,Donatello,,12345.6789また、カラム名のリストを指定することで、指定したカラム名で出力することができます。
buffer = io.StringIO()
df.to_csv(buffer, header=["名前", "マスク", "番号"])
print(buffer.getvalue())
>>
,名前,マスク,番号
0,Raphael,red,55110.0001
1,Donatello,,12345.6789index
インデックス列の出力有無を指定します。デフォルトはTrueです。
buffer = io.StringIO()
df.to_csv(buffer, index=False)
print(buffer.getvalue())
>>
name,mask,number
Raphael,red,55110.0001
Donatello,,12345.6789index_label
インデックス列のカラム名として出力する値を指定します。この、index及びheaderがともにFalseでないことが条件です。
buffer = io.StringIO()
df.to_csv(buffer, index_label="インデックス")
print(buffer.getvalue())
>>
インデックス,name,mask,number
0,Raphael,red,55110.0001
1,Donatello,,12345.6789マルチインデックスの場合は、リスト形式で指定することも可能です。CSV上では、インデックスか通常のカラムかといった見分けはつきません。
# nameもインデックスとして追加（マルチインデックス化）
df = df.set_index('name', append=True)
buffer = io.StringIO()
df.to_csv(buffer, index_label=["インデックス", "インデックス2"])
print(buffer.getvalue())
>>
インデックス,インデックス2,mask,number
0,Raphael,red,55110.0001
1,Donatello,,12345.6789また、index_label=Falseとすると、インデックス列のカラム名が出力されなくなります（インデックスの値は出力される）。
以下ではname列をインデックスに加えた状態でindex_label=Falseを指定しています。ヘッダー行のみ出力されなくなっています。
# nameもインデックスとして追加（マルチインデックス化）
df = df.set_index('name', append=True)
buffer = io.StringIO()
df.to_csv(buffer, index_label=False)
print(buffer.getvalue())
>>
mask,number
0,Raphael,red,55110.0001
1,Donatello,,12345.6789mode
ファイルを開く際のモードを指定します。‘w’, ‘x’, ‘a’から指定可能です。
| 値 | 意味 |
|---|---|
| ‘w’ | 既に同一のファイルが存在する場合、当該ファイルを削除のうえ、出力ファイルを新規作成する |
| ‘x’ | 既に同一のファイルが存在する場合はエラーとする |
| ‘a’ | 既に同一のファイルが存在する場合は当該ファイルに追記する |
buffer = io.StringIO()
df.to_csv(buffer, mode="w")
print(buffer.getvalue())
encoding
出力ファイルの文字コードを指定します。指定できる文字コードはPython標準に準拠します。
buffer = io.StringIO()
df.to_csv(buffer, encoding="utf-8")
print(buffer.getvalue())
compression
zipやtarなどの圧縮形式で出力する引数です。
zip形式で圧縮した状態で出力する場合、以下のように指定します。
compression_opts = dict(method='zip', archive_name='out.csv')
df.to_csv('output/out.zip', compression=compression_opts)quoting
引用符の取扱いを指定する引数で、以下の４つを指定可能です。対応する整数を指定する必要があります。
デフォルトはcsv.QUOTE_MINIMALで、ダブルクォートを引用符と認識します。
df.to_csv(buffer, quoting=0)
>>
,name,mask,number
0,Raphael,red,55110.0001
1,Donatello,,12345.6789df.to_csv(buffer, quoting=1)
>>
"","name","mask","number"
"0","Raphael","red","55110.0001"
"1","Donatello","","12345.6789"df.to_csv(buffer, quoting=2)
>>
"","name","mask","number"
0,"Raphael","red",55110.0001
1,"Donatello","",12345.6789df.to_csv(buffer, quoting=3)
>>
,name,mask,number
0,Raphael,red,55110.0001
1,Donatello,,12345.6789quotechar
引用符の文字を指定します。デフォルトはダブルクォート(“)です。
基本的にquotingと併せて使用します。
以下では、quotecharをシングルクォート(‘)に指定しています。
buffer = io.StringIO()
df.to_csv(buffer, quoting=1, quotechar="'")
print(buffer.getvalue())
>>
'','name','mask','number'
'0','Raphael','red','55110.0001'
'1','Donatello','','12345.6789'date_format
日付型データの出力フォーマットを文字列で指定します。
検証のため、データフレームに日付型を追加します。
df['date'] = pd.to_datetime(['2025-05-05', '2025-05-06'])
df.to_dict(orient='records')
>>
[{'name': 'Raphael',
'mask': 'red',
'number': 55110.0001,
'date': Timestamp('2025-05-05 00:00:00')},
{'name': 'Donatello',
'mask': None,
'number': 12345.6789,
'date': Timestamp('2025-05-06 00:00:00')}]date列のフォーマットを”%Y/%m/%d”として出力するには、以下のように指定します。
buffer = io.StringIO()
df.to_csv(buffer, date_format="%Y/%m/%d")
print(buffer.getvalue())
>>
,name,mask,number,date
0,Raphael,red,55110.0001,2025/05/05
1,Donatello,,12345.6789,2025/05/06errors
エンコードやデコード時にエラーが発生した際のハンドリングを指定します。以下の５つから指定でき、デフォルトは’strict’です。
| 値 | 意味 |
|---|---|
| ‘strict’ | 変換できない文字があると、UnicodeErrorを送出する。 |
| ‘ignore’ | 変換できない値は無視される。 |
| ‘replace’ | 変換できない文字は�（U+FFFD）に変換される。 |
| ‘backslashreplace’ | 変換できない文字はバックスラッシュのエスケープシーケンス（\xhh、 \uxxxx、 \Uxxxxxxxx）に変換される。 |
| ‘surrogateescape’ | 変換できない文字はサロゲートコードポイント (0xDC00 – 0xDFFF)に変換される。 |
buffer = io.StringIO()
df.to_csv(buffer, errors="replace")Pythonでデータサイエンスするなら
Pythonでデータサイエンスをするなら、以下の書籍がおすすめです。Pandas、matplotlib、Numpy、scikit-learnといったデータサイエンスに必要なライブラリを、体系立てて一通り学ぶことができます。
ややお値段高めですが、これ1冊で十分という内容・ボリュームなので、損はしないと思います^^
まとめ
pandasでデータフレームをCSVファイルに出力する方法を紹介しました。CSVファイルをPythonで扱うケースはかなりあると思うので、是非参考にしてみてください。
今回もかなりの量の引数を紹介したが、こういう引数あったなくらいで覚えておけばよい。後は、都度調べて使えるようになれば良いだろう。
今回はここまで。次回は、データフレームをCSVファイルとして出力する方法を紹介する。
ありがとうございました～～♪