Pandas to_excelでよくあるエラーと解決策：完全ガイド

2025-06-06

簡単に言うと、Python で作成したり加工したりした表形式のデータを、Excel で開ける形式で保存したいときに使います。

基本的な使い方

最も基本的な使い方は、保存したいファイル名を引数として渡すだけです。

import pandas as pd

# サンプルDataFrameの作成
data = {'名前': ['アリス', 'ボブ', 'チャーリー'],
        '年齢': [25, 30, 35],
        '職業': ['エンジニア', '医師', 'アーティスト']}
df = pd.DataFrame(data)

# Excelファイルとして保存
df.to_excel('出力ファイル.xlsx')

このコードを実行すると、スクリプトが実行されたのと同じディレクトリに 出力ファイル.xlsx という Excel ファイルが作成され、その中に df の内容が書き込まれます。

よく使う引数 (parameters)

to_excel メソッドには、出力の挙動を細かく制御するための様々な引数があります。いくつか主要なものを紹介します。

engine:
- (デフォルト: None) Excel ファイルの読み書きに使用するエンジンを指定します。通常は明示的に指定する必要はありませんが、特定の環境で問題が発生する場合や、高度な機能 (例: 書式設定) を使いたい場合に openpyxl や xlsxwriter などを指定することがあります。これらのエンジンは別途インストールが必要です (pip install openpyxl xlsxwriter など)。
```
# xlsxwriter エンジンを使用する場合
df.to_excel('出力ファイル.xlsx', engine='xlsxwriter')
```
freeze_panes:
- (デフォルト: None) Excel の「ウィンドウ枠の固定」を設定します。タプル (行, 列) で指定します。
```
# 1行目と1列目を固定する場合 (ヘッダーと最初の列)
df.to_excel('出力ファイル.xlsx', freeze_panes=(1, 1))
```

na_rep:

(デフォルト: 空文字) DataFrame 内の欠損値 (NaN) を Excel に書き込む際に、何で表現するかを指定します。

# 欠損値を 'N/A' と表示する場合
import numpy as np
df_with_nan = pd.DataFrame({'A': [1, 2, np.nan], 'B': [4, 5, 6]})
df_with_nan.to_excel('出力ファイル.xlsx', na_rep='N/A')

columns:

(デフォルト: None) Excel に書き込む列を指定します。列名のリストを渡します。

# 特定の列のみを書き込む場合
df.to_excel('出力ファイル.xlsx', columns=['名前', '職業'])

header:
- (デフォルト: True) DataFrame のヘッダー (列の名前) を Excel に書き込むかどうかを指定します。
```
# ヘッダーを書き込まない場合
df.to_excel('出力ファイル.xlsx', header=False)
```
index:
- (デフォルト: True) DataFrame のインデックス (行の名前) を Excel に書き込むかどうかを指定します。
```
# インデックスを書き込まない場合
df.to_excel('出力ファイル.xlsx', index=False)
```
sheet_name:
- (デフォルト: 'Sheet1') Excel シートの名前を指定します。
```
df.to_excel('出力ファイル.xlsx', sheet_name='従業員データ')
```
excel_writer:
- Excel ファイルのパス (文字列) を指定します。上記の例のように直接ファイル名を指定するのが一般的です。
- または、pandas.ExcelWriter オブジェクトを渡すこともできます。これを使うと、複数の DataFrame を同じ Excel ファイル内の異なるシートに書き込むことができます。

ExcelWriter を使うと、一つの Excel ファイル内に複数のシートを作成し、それぞれに異なる DataFrame を書き込むことができます。

import pandas as pd

df1 = pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
df2 = pd.DataFrame({'X': [10, 20], 'Y': [30, 40]})

with pd.ExcelWriter('複数シートファイル.xlsx') as writer:
    df1.to_excel(writer, sheet_name='シート1', index=False)
    df2.to_excel(writer, sheet_name='シート2', index=False)

このコードを実行すると、複数シートファイル.xlsx という Excel ファイルが作成され、「シート1」と「シート2」という2つのシートにそれぞれの DataFrame の内容が書き込まれます。

ModuleNotFoundError: No module named 'openpyxl' または 'xlsxwriter'

エラー内容
df.to_excel() を実行しようとすると、openpyxl や xlsxwriter といったモジュールが見つからないというエラーが出ることがあります。

ModuleNotFoundError: No module named 'openpyxl'

原因
pandas が Excel ファイル（特に.xlsx形式）を書き込むためには、内部的にこれらの追加ライブラリのいずれかが必要です。デフォルトでは openpyxl が使用されますが、インストールされていない場合にこのエラーが発生します。

解決策
必要なライブラリを pip でインストールします。

特定の機能（チャートの埋め込みなど）やパフォーマンス要件がある場合、または openpyxl で問題が発生する場合:
```
pip install xlsxwriter
```
to_excel メソッドで engine='xlsxwriter' を明示的に指定することもできます。
```
df.to_excel('ファイル名.xlsx', engine='xlsxwriter')
```
.xls ファイルを扱う場合（古いExcel形式）や、より高度な書式設定が必要な場合:
```
pip install xlwt
```
.xlsx ファイルを扱う場合:
```
pip install openpyxl
```

ファイルのロック/アクセス拒否エラー (PermissionError など)

エラー内容
Excel ファイルを書き込もうとしたときに、ファイルがすでに開かれている、またはアクセス権がないために書き込みができないというエラーが発生することがあります。

PermissionError: [Errno 13] Permission denied: '出力ファイル.xlsx'

または

OSError: [Errno 22] Invalid argument: 'C:\\path\\to\\file.xlsx'

原因

無効なファイルパス/ファイル名
ファイルパスに無効な文字が含まれていたり、存在しないディレクトリを指定している場合。
書き込み権限がないディレクトリ
ファイルを保存しようとしているディレクトリに、現在のユーザーが書き込み権限を持っていない場合に発生します。
ファイルが別のプログラムで開かれている
Excel ファイルが Excel アプリケーションで開かれているか、他のPythonスクリプトなどによってロックされている場合に発生します。

解決策

無効な文字の確認
ファイル名やパスに /, \, ?, *, <, >, |, " などの無効な文字が含まれていないか確認します。
絶対パスを指定する
相対パスではなく、C:\\Users\\YourUser\\Documents\\出力ファイル.xlsx のように絶対パスで指定することで、パスの問題を解決できる場合があります。
一時ファイルとして保存し、後で移動する
共有環境などで頻繁にロックされる場合は、一時ファイルとして別の場所に保存し、後で手動またはスクリプトで目的の場所に移動することを検討します。
書き込み権限を確認する
ファイルを保存するディレクトリの権限を確認し、必要に応じて書き込み権限を付与してください。
開いているファイルを閉じる
Excel ファイルが Excel アプリケーションなどで開かれている場合は、ファイルを閉じてからスクリプトを再実行してください。

UnicodeEncodeError: 'ascii' codec can't encode characters in position ...

原因
Excel ファイル自体は通常UTF-8をサポートしていますが、古いバージョンのpandasや特定の環境設定によってエンコーディングの問題が発生することがあります。

解決策
通常、to_excelはデフォルトでUnicodeを適切に処理するため、明示的なエンコーディング指定はあまり必要ありません。しかし、問題が発生する場合は以下の点を考慮します。

Excel側での読み込み設定
Excelでファイルを開く際に、エンコーディング設定（データ取り込みウィザードなど）を確認する必要がある場合もありますが、to_excelで作成された.xlsxファイルであれば通常は自動的に認識されます。
xlsxwriter エンジンの利用
xlsxwriter はエンコーディングに対してより堅牢な場合があります。
```
df.to_excel('ファイル名.xlsx', engine='xlsxwriter')
```
データ自体のクリーンアップ
DataFrame内に、Excelで扱いにくい特殊な制御文字などが含まれていないか確認し、必要に応じて除去または置換します。
最新のpandasと関連ライブラリを使用する
古いバージョョンではバグがある可能性があります。

メモリ不足エラー (MemoryError)

エラー内容
非常に大きなDataFrameをExcelに書き込もうとすると、メモリ不足のエラーが発生することがあります。

MemoryError

原因
Excelファイルは、CSVなどと異なり、データをメモリ上で処理しながら書き込むため、DataFrameが非常に大きい場合（数百万行など）に多くのメモリを消費します。

解決策

他のフォーマットを検討する
非常に大きなデータを扱う場合は、CSVファイルやデータベース、Parquetなどのよりメモリ効率の良いフォーマットへの出力も検討します。
データ型を最適化する
数値データが不必要に大きなデータ型（例: float64が必要ないのに使用されている）である場合、より小さなデータ型（例: float32）に変換することでメモリ使用量を減らせる可能性があります。
不要な列を削除する
Excelに出力する必要のない列があれば、事前にDataFrameから削除してメモリ使用量を減らします。
データを分割して書き込む
大きなDataFrameを小さなチャンクに分割し、それぞれを異なるシートや別のExcelファイルに書き込みます。

エラー内容
指定したパスにファイルを作成できない、またはパスが無効であるというエラーが出ます。

FileNotFoundError: [Errno 2] No such file or directory: '存在しないディレクトリ/出力ファイル.xlsx'

原因
指定したディレクトリが存在しない場合に発生します。

パスの誤字脱字を確認する
パスに間違いがないか、改めて確認します。

ディレクトリを作成する
os.makedirs() を使って、ファイル保存前にディレクトリが存在することを確認し、なければ作成します。

import pandas as pd
import os

output_dir = '出力データ'
output_file = os.path.join(output_dir, '結果.xlsx')

# ディレクトリが存在しない場合は作成
if not os.path.exists(output_dir):
    os.makedirs(output_dir)

df = pd.DataFrame({'A': [1], 'B': [2]})
df.to_excel(output_file, index=False)

基本的な使い方：DataFrameをExcelファイルに保存する

最もシンプルな例です。DataFrameをExcelファイルとして保存します。

import pandas as pd

# サンプルDataFrameを作成
data = {
    '商品名': ['りんご', 'バナナ', 'みかん', 'ぶどう'],
    '価格': [100, 80, 120, 250],
    '在庫数': [50, 120, 75, 30]
}
df = pd.DataFrame(data)

# DataFrameをExcelファイルとして保存
# ファイル名は '商品リスト.xlsx' となります
# デフォルトではシート名が 'Sheet1' となり、インデックスが1列目に出力されます
df.to_excel('商品リスト.xlsx')

print("『商品リスト.xlsx』が正常に作成されました。")

出力されるExcelファイル (商品リスト.xlsx) のイメージ

	商品名	価格	在庫数
0	りんご	100	50
1	バナナ	80	120
2	みかん	120	75
3	ぶどう	250	30

オプションを指定した保存：インデックス、ヘッダー、シート名の調整

to_excel のよく使われるオプションを使って、出力形式を調整します。

import pandas as pd

data = {
    '従業員ID': [101, 102, 103, 104],
    '名前': ['田中', '佐藤', '鈴木', '高橋'],
    '部署': ['営業', '開発', '人事', '営業'],
    '入社年': [2020, 2018, 2022, 2021]
}
df = pd.DataFrame(data)

# オプションを指定してExcelファイルに保存
# - index=False: DataFrameのインデックスを出力しない
# - header=True: DataFrameのヘッダー（列名）を出力する (デフォルトもTrue)
# - sheet_name='社員情報': シート名を '社員情報' に設定
df.to_excel('社員データ.xlsx', index=False, header=True, sheet_name='社員情報')

print("『社員データ.xlsx』がオプション付きで正常に作成されました。")

出力されるExcelファイル (社員データ.xlsx) のイメージ

従業員ID	名前	部署	入社年
101	田中	営業	2020
102	佐藤	開発	2018
103	鈴木	人事	2022
104	高橋	営業	2021

特定の列のみを保存する

columns 引数を使って、DataFrameの一部の列だけをExcelに出力できます。

import pandas as pd

data = {
    '日付': ['2025-01-01', '2025-01-02', '2025-01-03'],
    '売上': [10000, 12000, 9500],
    '費用': [3000, 3500, 2800],
    '利益': [7000, 8500, 6700]
}
df = pd.DataFrame(data)

# '日付' と '売上' の列のみをExcelに保存
df.to_excel('日次売上.xlsx', columns=['日付', '売上'], index=False)

print("『日次売上.xlsx』が選択された列のみで正常に作成されました。")

出力されるExcelファイル (日次売上.xlsx) のイメージ

日付	売上
2025-01-01	10000
2025-01-02	12000
2025-01-03	9500

複数のDataFrameを同じExcelファイルの異なるシートに保存する

pandas.ExcelWriter を使用すると、一つのExcelファイル内に複数のシートを作成し、それぞれに異なるDataFrameを書き込むことができます。これは非常に強力な機能です。

import pandas as pd

# 最初のDataFrame
df_sales = pd.DataFrame({
    '月': ['1月', '2月', '3月'],
    '売上高': [150000, 160000, 145000]
})

# 2つ目のDataFrame
df_expenses = pd.DataFrame({
    '月': ['1月', '2月', '3月'],
    '広告費': [10000, 11000, 9500],
    '人件費': [50000, 52000, 51000]
})

# ExcelWriterオブジェクトを作成
# 'with' ステートメントを使うことで、ファイルを確実に閉じることができます
with pd.ExcelWriter('月次レポート.xlsx') as writer:
    # 最初のDataFrameを '売上データ' シートに保存
    df_sales.to_excel(writer, sheet_name='売上データ', index=False)

    # 2つ目のDataFrameを '費用データ' シートに保存
    df_expenses.to_excel(writer, sheet_name='費用データ', index=False)

print("『月次レポート.xlsx』に複数のシートが正常に作成されました。")

出力されるExcelファイル (月次レポート.xlsx) のイメージ

シート1: 売上データ

月	売上高
1月	150000
2月	160000
3月	145000

シート2: 費用データ

月	広告費	人件費
1月	10000	50000
2月	11000	52000
3月	9500	51000

欠損値 (NaN) の表現を変更する

DataFrame内の欠損値 (NaN) をExcelでどのように表示するかを na_rep 引数で指定できます。

import pandas as pd
import numpy as np # NaN を使うために必要

data = {
    'A': [1, 2, np.nan, 4],
    'B': [5, 6, 7, np.nan],
    'C': [8, np.nan, 10, 11]
}
df = pd.DataFrame(data)

# 欠損値を 'データなし' と表示してExcelに保存
df.to_excel('欠損値例.xlsx', na_rep='データなし', index=False)

print("『欠損値例.xlsx』が欠損値の表示をカスタマイズして正常に作成されました。")

出力されるExcelファイル (欠損値例.xlsx) のイメージ

A	B	C
1	5	8
2	6	データなし
データなし	7	10
4	データなし	11

Excelの「ウィンドウ枠の固定」を設定することで、スクロールしても特定の行や列が表示され続けるようにできます。

import pandas as pd

# 大きめのDataFrameを作成
long_data = {f'列{i}': list(range(i, i + 100)) for i in range(1, 10)}
df_large = pd.DataFrame(long_data)

# 最初の1行と最初の1列を固定してExcelに保存
# (1, 1) は1行目と1列目のすぐ下と右に固定線を引くことを意味します
# つまり、ヘッダー行と最初の列が固定されます
df_large.to_excel('固定枠例.xlsx', freeze_panes=(1, 1))

print("『固定枠例.xlsx』がウィンドウ枠の固定付きで正常に作成されました。")

このファイルをExcelで開くと、1行目と1列目が固定されていることが確認できます。

これらの例を実行する前に、以下のライブラリがインストールされていることを確認してください。

pip install pandas openpyxl

特に openpyxl は .xlsx 形式のファイルを扱うために pandas が内部的に使用します。

xlsxwriter または openpyxl ライブラリを直接使用する

pandas.DataFrame.to_excel は内部的に openpyxl や xlsxwriter といったライブラリを利用してExcelファイルを生成しています。これらのライブラリを直接使用することで、pandas の to_excel ではカバーしきれない、より詳細なExcelの書式設定や機能（グラフの埋め込み、条件付き書式、データの入力規則など）を制御できます。

特徴

デメリット
pandas.DataFrame をExcelに書き出すためのコードが複雑になる、pandas の便利さ（データ型に応じた自動変換など）を直接享受できない。
メリット
Excelファイルの書式設定を非常に細かく制御できる、グラフや図形の埋め込みなど高度な機能を利用できる。

コード例（xlsxwriter を使用した書式設定の例）

import pandas as pd
import xlsxwriter # pip install xlsxwriter が必要

df = pd.DataFrame({
    '商品': ['A', 'B', 'C'],
    '売上': [1000, 1500, 800],
    '利益率': [0.10, 0.12, 0.08]
})

output_file = '高度なExcelレポート.xlsx'

# ExcelWriterオブジェクトを作成し、engineに 'xlsxwriter' を指定
with pd.ExcelWriter(output_file, engine='xlsxwriter') as writer:
    # DataFrameをシートに書き込む
    df.to_excel(writer, sheet_name='レポート', index=False, startrow=1) # 1行目を空けて書き込み

    # xlsxwriter の workbook および worksheet オブジェクトを取得
    workbook = writer.book
    worksheet = writer.sheets['レポート']

    # ヘッダーに書式を設定（例：太字、背景色）
    header_format = workbook.add_format({
        'bold': True,
        'bg_color': '#D7E4BC', # 薄い緑色
        'border': 1
    })
    for col_num, value in enumerate(df.columns.values):
        worksheet.write(0, col_num, value, header_format) # ヘッダー行に書き込む

    # '売上' 列に通貨書式を設定
    money_format = workbook.add_format({'num_format': '#,##0'})
    worksheet.set_column('B:B', None, money_format) # B列全体に適用

    # '利益率' 列にパーセンテージ書式を設定
    percent_format = workbook.add_format({'num_format': '0.0%'})
    worksheet.set_column('C:C', None, percent_format) # C列全体に適用

    # 列幅を自動調整（これは xlsxwriter のみが提供する機能ではありませんが、例として）
    for i, col in enumerate(df.columns):
        max_len = max(df[col].astype(str).map(len).max(), len(col)) + 2 # 列名とデータで長い方に合わせる
        worksheet.set_column(i, i, max_len)

print(f"『{output_file}』が高度な書式設定で作成されました。")

この例では、to_excel で基本的なデータを書き込んだ後、xlsxwriter の機能を使ってヘッダーの書式設定、通貨やパーセンテージの表示形式の適用、列幅の自動調整を行っています。

CSVファイルとして出力する

Excelファイルではなく、カンマ区切り（またはタブ区切りなど）のテキストファイルとしてデータを保存する方法です。

特徴

デメリット
Excel固有の書式設定（フォント、色、グラフなど）は保存できない。
メリット
非常にシンプルで高速、メモリ使用量が少ないため大規模データ向き、汎用性が高く他のシステムとの連携が容易。

コード例

import pandas as pd

df = pd.DataFrame({
    'ID': [1, 2, 3],
    '名前': ['Alice', 'Bob', 'Charlie'],
    'スコア': [85, 92, 78]
})

# CSVファイルとして保存
df.to_csv('データ.csv', index=False, encoding='utf-8-sig') # 日本語対応のため 'utf-8-sig' を推奨

print("『データ.csv』が正常に作成されました。")

# タブ区切り（TSV）として保存する例
df.to_csv('データ.tsv', sep='\t', index=False, encoding='utf-8-sig')
print("『データ.tsv』が正常に作成されました。")

Parquet, HDF5, Feather などのバイナリ形式で出力する

これらは、大量のデータを効率的に保存・読み込みするために設計されたファイル形式です。主にデータ分析ワークフローの中で中間データを保存する場合や、異なるプログラミング言語間でデータを共有する場合に利用されます。Excelファイルとは異なり、人間が直接読み書きする目的ではありません。

特徴

デメリット
Excelのような可読性はない、専用のライブラリ（pyarrow, fastparquet など）が必要。
メリット
非常に高速な読み書き、高いデータ圧縮率、データ型情報の保持（スキーマの保存）、大規模データセットに最適。

コード例（Parquet形式）

import pandas as pd
# pip install pyarrow fastparquet が必要

df_large = pd.DataFrame({
    '数値データ': range(1000000),
    'カテゴリデータ': ['A'] * 500000 + ['B'] * 500000
})

# Parquetファイルとして保存
df_large.to_parquet('大規模データ.parquet', index=False)

print("『大規模データ.parquet』が正常に作成されました。")

# 後で読み込む例
df_reloaded = pd.read_parquet('大規模データ.parquet')
print("Parquetファイルからデータを読み込みました。")
print(df_reloaded.head())

データベースに保存する

DataFrameのデータを直接リレーショナルデータベース（SQLite, PostgreSQL, MySQLなど）に書き込む方法です。

特徴

デメリット
データベースの設定と接続が必要、スキーマの管理が必要。
メリット
データの永続化と管理、SQLによる柔軟なクエリ、複数のアプリケーションからのアクセス、トランザクション管理。

import pandas as pd
import sqlalchemy # pip install sqlalchemy が必要

df = pd.DataFrame({
    '顧客ID': [1, 2, 3],
    '顧客名': ['山本', '加藤', '中村'],
    '最終購入日': ['2024-05-01', '2024-04-15', '2024-05-20']
})

# SQLiteデータベースへの接続文字列
# ':memory:' は一時的なインメモリデータベース
# 'customers.db' とするとファイルとして保存されます
engine = sqlalchemy.create_engine('sqlite:///customers.db')

# DataFrameをデータベースのテーブルに書き込む
# if_exists='replace': テーブルが存在すれば置き換える
# index=False: DataFrameのインデックスをテーブルに含めない
df.to_sql('customers', con=engine, if_exists='replace', index=False)

print("データが『customers.db』の 'customers' テーブルに保存されました。")

# データベースからデータを読み込む例
df_from_db = pd.read_sql('SELECT * FROM customers', con=engine)
print("\nデータベースから読み込んだデータ:")
print(df_from_db)

データの永続的な管理、SQLによるクエリ、複数アプリケーションからのアクセス
データベース (df.to_sql())。
超大規模なデータセットを扱う、高速な読み書きが必要、データ分析パイプラインの一部
Parquet, HDF5, Feather。
Excel固有の機能は不要、他のシステムとの連携が多い、テキストベースでよい
df.to_csv()。
Excelの書式設定を細かく制御したい、グラフを埋め込みたい
xlsxwriter や openpyxl を直接使う。
簡単なExcel出力で十分、書式は最低限でOK
df.to_excel() がベスト。