【Pandas】データフレームをCSVファイルとして書き出す

2025年5月5日
2026年3月8日
Pandas, Python
Pandas, Python

Pandas

データ分析の結果や加工済みデータをCSVファイルとして書き出すことは、データ連携やレポーティングの場面で頻繁に行われます。

この記事では、DataFrame.to_csv()の基本的な使い方から、よく使う引数の詳細まで解説します。

Pandasバージョン

本記事は、Pandas 2.2.3の情報を基に執筆しています。

import pandas as pd
print(pd.__version__)

>>
2.2.3

DataFrame.to_csv()

CSVファイルへの出力には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		出力ファイルのパスまたはバッファ。省略時は文字列として返される
sep		区切り文字。デフォルトは`','`
na_rep		欠損値の表現。デフォルトは`''`
float_format		float型の出力フォーマット
columns		出力カラムをリストで指定
header		ヘッダーの出力有無。リスト指定で列名の変更も可能
index		インデックスの出力有無。デフォルトは`True`
index_label		インデックス列の列名を指定
mode		ファイルを開くモード（`'w'`, `'x'`, `'a'`）
encoding		文字コードを指定
compression		圧縮形式を指定
quoting		引用符の取扱い
quotechar		引用符の文字
lineterminator		行末文字
chunksize		一度に出力する行数
date_format		日付型データの出力フォーマット
doublequote		値中の引用符の取扱い
escapechar		エスケープ文字
decimal		小数点の文字
errors		エンコードエラー時の処理
storage_options		リモートファイルアクセス情報

以降では、よく使う引数を中心に具体例とともに解説します。

基本引数

以下のデータフレームを使用して検証します。

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

出力先を指定しない場合は、CSV形式の文字列が返されます。

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(buffer, sep=";")
print(buffer.getvalue())

>>
;name;mask;number
0;Raphael;red;55110.0001
1;Donatello;;12345.6789

na_rep

欠損値（NoneやNaN）の出力表現を指定します。デフォルトでは空文字（''）として出力されます。

buffer = io.StringIO()
df.to_csv(buffer, na_rep="欠損値")
print(buffer.getvalue()) 

>>
,name,mask,number
0,Raphael,red,55110.0001
1,Donatello,欠損値,12345.6789

float_format

浮動小数点数の出力フォーマットを指定します。"%.2f"とした場合、小数第2位まで出力されます。

buffer = io.StringIO()
df.to_csv(buffer, float_format="%.2f")
print(buffer.getvalue())

>>
,name,mask,number
0,Raphael,red,55110.00
1,Donatello,,12345.68

columns

出力対象のカラムをリスト形式で指定します。

buffer = io.StringIO()
df.to_csv(buffer, columns=["name", "number"])
print(buffer.getvalue())

>>
,name,number
0,Raphael,55110.0001
1,Donatello,12345.6789

header

ヘッダーの出力有無を指定します。デフォルトは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.6789

index

インデックス列の出力有無を指定します。デフォルトはTrueです。

buffer = io.StringIO()
df.to_csv(buffer, index=False)
print(buffer.getvalue())

>>
name,mask,number
Raphael,red,55110.0001
Donatello,,12345.6789

index_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

マルチインデックスの場合は、リスト形式で指定します。

# 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もインデックスとして追加（マルチインデックス化）
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.6789

mode

ファイルを開く際のモードを指定します。

値	意味
`'w'`	同名ファイルが存在する場合、上書きして新規作成する
`'x'`	同名ファイルが存在する場合はエラーとする
`'a'`	同名ファイルが存在する場合は末尾に追記する

df.to_csv('output/out.csv', mode="w")

encoding

出力ファイルの文字コードを指定します。指定できる文字コードはPython標準に準拠します。

df.to_csv('output/out.csv', encoding="utf-8")
df.to_csv('output/out.csv', encoding="cp932")

compression

圧縮形式（zip、tarなど）で出力する場合に指定します。

compression_opts = dict(method='zip', archive_name='out.csv')
df.to_csv('output/out.zip', compression=compression_opts)

quoting

引用符の取扱いを指定します。以下の4つの値が指定可能です。デフォルトはcsv.QUOTE_MINIMALです。

df.to_csv(buffer, quoting=0)

>>
,name,mask,number
0,Raphael,red,55110.0001
1,Donatello,,12345.6789

df.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.6789

df.to_csv(buffer, quoting=3)

>>
,name,mask,number
0,Raphael,red,55110.0001
1,Donatello,,12345.6789

quotechar

引用符の文字を指定します。デフォルトはダブルクォート（"）です。quotingと組み合わせて使用します。

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'])

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/06

errors

エンコード・デコードエラー時のハンドリングを指定します。デフォルトは'strict'です。

値	意味
`'strict'`	変換できない文字があると`UnicodeError`を送出する
`'ignore'`	変換できない値は無視される
`'replace'`	変換できない文字は`�`（U+FFFD）に変換される
`'backslashreplace'`	変換できない文字はバックスラッシュのエスケープシーケンスに変換される
`'surrogateescape'`	変換できない文字はサロゲートコードポイントに変換される

df.to_csv('output/out.csv', errors="replace")

まとめ

今回は、DataFrame.to_csv()を使ったCSVファイルへの出力方法を紹介しました。

基本的な出力: df.to_csv("ファイルパス")で簡単にCSV出力できる
インデックス制御: index=Falseで不要なインデックス列を除外可能
欠損値の表現: na_repで欠損値の出力表現をカスタマイズ可能
日付フォーマット: date_formatで日付型データの出力形式を指定可能
文字コード: encodingで出力ファイルの文字コードを制御可能

用途に応じて適切な引数を設定し、連携先のシステムやツールに合った形式でデータを出力してください。