pandasのto_excelで書き込みエラーが出る原因と対処法を試した話

Pythonでなんとか集計まで終わらせて、あとはto_excelでExcelに出すだけ。そう思った最後の一歩で、真っ赤なエラーが出て止まったことが何度もありました。集計のコードは合っているのに、保存のところだけ通らないのです。私はプログラミングのプの字も知らない事務職からの独学なので、最初は原因の見当もつきませんでした。ここでは、私がto_excelでつまずいた4つのエラーと、そのとき試したことを共有します。同じところで止まっている方の、回り道を少しでも減らせたらと思って書きました。

to_excel出力のつまずき4選

私が最初にto_excelを使ったのは、毎月の売上を部署ごとに集計したファイルを出す作業でした。手作業で30分かけていた集計をPythonに置き換えられて、ここまでは順調だったのです。ところが、出力の行を実行した瞬間に処理が赤い文字で止まりました。集計結果はメモリ上にちゃんと出来ているのに、ファイルとして保存だけができない状態です。最初は自分の集計コードが壊れたのかと思い、関係ない部分ばかり見直して時間を溶かしました。あとから振り返ると、to_excelで止まる原因はだいたい決まった4パターンに収まっていました。

ファイルを開いたままにしている、追記モードのエンジン指定、データに混ざった見えない文字、保存先のパスの書き方です。どれも集計ロジックとは別の、保存まわりのつまずきでした。ここからは、その4つを私がつまずいた順番に振り返っていきます。

PermissionErrorはExcelの閉じ忘れ

最も頻繁に遭遇し、かつ原因が単純なエラーがあります。それが「PermissionError」です。これは、書き出し先のExcelファイルを自分で開いている時に発生します。Windowsの仕組みとして制限がかかるからです。他のソフトがファイルを開いている間は上書きできません。直前にデータを確認しようとしてファイルを開いたままにします。すると、プログラムからの保存に失敗してしまうのです。VS Codeなどのコンソール画面を確認してください。「WinError 32: プロセスはファイルにアクセスできません」と出ます。Excelで直前の集計結果を確認しました。

そのまま閉じずにPythonのプログラムを再実行してしまったのです。すると、何度やってもPermissionErrorが出ました。プログラムのバグだと思い込み、1時間もコードを修正する羽目になったのです。結局、ただExcelを閉じるだけで解決したと気づきました。その時は、自分のうっかり具合に脱力してしまったものです。このエラーへの対策は非常に簡単です。まず、出力先のファイルを完全に閉じてください。それから、再度プログラムを実行すれば完了します。

開いてないのにエラー？タスクと同期の確認

もしファイルを開いていないのにエラーが出たらどうでしょうか。バックグラウンドでプロセスが残っている可能性があります。そんなときは、タスクマネージャーを開きましょう。一覧の中に「Microsoft Excel」が残っていたら、選んでタスクを終了します。プレビュー表示やクラウド同期のソフトがファイルをつかんでいることもありました。私はOneDrive上のファイルに書き込もうとして、同期中につかまれていた経験もあります。出力先はいったんデスクトップなど手元のフォルダにすると、原因の切り分けが楽になりました。

Excel追記エラーとエンジン指定

既存のExcelファイルにデータを追加したい場合があります。新しいデータを新しいシートとして保存する処理です。そこで、pd.ExcelWriterで追記モードを指定します。「mode=’a’」を設定すると、エラーで止まることがあります。特定のエラーメッセージが出た時は注意が必要です。「Append mode is not supported…」という内容が表示されます。実は、pandasが標準で使おうとするエンジンが原因です。「xlsxwriter」は既存ファイルへの追記に対応していません。このエンジンは、ファイルを新規作成することに特化しています。

すでに存在する中身を書き換えることができない仕様です。前月の売上データが入っているExcelがありました。今月のデータを追加しようとして追記モードを試します。しかし、何度やってもxlsxwriterのエラーで止まるのです。追記という基本的なことができないのかと絶望しました。ネットで調べるとエンジンの指定が必要だと分かります。openpyxlを使うように修正したところ、あっさりと成功しました。エンジンの違いなんて意識したこともなかったので、勉強になった体験です。

openpyxlでのシート追記と重複回避

追記を行いたい場合は、エンジンの指定を変更します。必ず「engine=’openpyxl’」を明示的に指定してください。書き方としては、with pd.ExcelWriter(‘売上.xlsx’, engine=’openpyxl’, mode=’a’) as writer: のように開きます。そのうえで df.to_excel(writer, sheet_name=’今月’) と書くと、既存ファイルに新しいシートが足されました。ひとつ注意したいのは、同じ名前のシートがあると扱いがややこしくなる点です。私は毎月のシート名を「2026-06」

のように年月で分けて、重複しないようにしています。新規でまるごと作り直してよいときは、mode=’a’を外して普通に書き出すほうが迷いませんでした。

見えない制御文字の罠

データの中に「制御文字」が含まれていることがあります。この場合、保存時に「IllegalCharacterError」が発生するのです。ExcelのオープンXML形式の仕様が関係しています。特定の特殊な文字をセルに書き込むことが禁止されているからです。目に見えないゴミのような文字が紛れ込むケースは少なくありません。Webサイトからのスクレイピングデータなどに混ざりがちです。顧客アンケートの結果をExcelに出力しようとしました。特定の行だけが原因でエラーが出てしまいます。画面上はきれいな日本語テキストに見えるはずです。

なぜエラーが出るのか全く分からず、丸一日かけて精査しました。結局、原因はコピペの際に混入した文字だったのです。それは画面に表示されない制御文字だと判明しました。正規表現で除去するコードを書くまで、ずっとエラーと戦い続けることになります。本当に疲れ果てた記憶があります。

見えない制御文字除去でExcelエラー解決

このエラーを解決するには、除去処理が必要です。データフレーム内の制御文字を取り除きましょう。具体的には、正規表現を使った置換処理を行います。Excel側で書き込みが禁止されているのは、コードでいうと\x00〜\x08、\x0B〜\x0C、\x0E〜\x1Fの範囲の制御文字です。私の場合は、この原因にたどり着いて除去コードを書き終えるまで、丸一日（およそ8時間）かかってしまいました。見た目はきれいなのに保存だけ通らないという状況だったので、犯人が見えない文字だと気づくのに本当に時間がかかったのです。

PythonでのWindowsパス問題と解決策

Windows環境で開発していると、パスの書き方でエラーが起きます。ファイルの保存場所を指定する文字列のことです。フォルダの区切り文字である「\」には注意してください。Pythonでは特別な意味を持ってしまうからです。例えば、「C:\Users\new_folder\output.xlsx」と書きます。すると、バックスラッシュとnが改行として解釈される仕組みです。その結果、パスの文字列が壊れてしまいます。ファイル名が正しくないというエラーが出て止まるのです。「OSError: Invalid argument」というようなメッセージが表示されます。

回避するための解決策は3つです。まず、パスの文字列の前に「r」をつける方法です。これで「raw文字列」として扱われます。次に、バックスラッシュを二重にして「\\」と書く手法もあります。いわゆるエスケープ処理を行う書き方です。さらに、私が一番おすすめする方法を紹介しましょう。Windowsであっても「/（スラッシュ）」を使う方法です。

Pythonのパス指定：スラッシュ活用でエラー知らず

実は、Pythonの内部ではスラッシュを使っても問題ありません。Windowsのパスを正しく解釈してくれるからです。これが最も間違いが少なくなるテクニックと言えます。プログラムの世界特有のルールを知らないと躓いてしまうでしょう。保存先を指定するだけの作業でもエラーになります。

pandas Excelエンジンの使い分け

pandasでExcelを扱う際、エンジンの選択は非常に重要です。現在、2種類のライブラリが主流となっています。「openpyxl」と「xlsxwriter」がよく使われます。実は、これらはそれぞれ得意なことがはっきりと分かれているのです。まず、openpyxlは読み込みも書き込みも可能です。既存ファイルへの追記も得意な万能選手と言えます。しかし、大規模なデータを書き込むスピードは少し遅めです。xlsxwriterに比べると処理に時間がかかってしまいます。一方で、xlsxwriterは書き込み専用のエンジンです。

処理が高速で、かつ多機能なグラフ作成や書式設定ができます。先ほどお話しした制御文字のエラーも回避してくれるでしょう。柔軟に処理してくれる機能が備わっているからです。そのため、私は目的に応じて使い分けています。既存のファイルにシートを追加したい時はopenpyxlです。新規で大量のデータを見栄え良く出したい時はxlsxwriterを使います。切り替えはto_excelの引数で指定するだけです。コードのうえでは、engine=’xlsxwriter’のように書けば完了します。

迷ったらopenpyxl、xlwtは旧形式専用

もし、どちらを使えばいいか迷った場合はどうすべきでしょうか。まずは標準的なopenpyxlを試してみるのが良いでしょう。ところが、古い解説サイトなどでは別のエンジンが紹介されています。特に書き込みでxlwtという名前を見かけますが、これは古い.xls形式専用のものです。今主流の.xlsxを書き出すときには使えないので、見かけても選ばないようにしています。どちらのエンジンも、使う前にpip install openpyxlのように入れておく必要がありました。インストールを忘れたまま指定すると、別のエラーで止まってしまうので気をつけてください。

to_excelエラー解決の実践チェックリスト

エラーが出た時、焦ってコードを闇雲にいじり回すのは逆効果です。そこで、私が実際に現場で使っているチェックリストをまとめました。トラブル解決の手順として活用してください。まず、最初に見るべきは「そのExcelファイルを開いていないか」です。もし開いていたら、迷わず閉じてから再実行します。これで解決することが驚くほど多いのです。次に、保存先のフォルダが本当に存在するか確認します。パスの書き方が間違っていないかも大切なポイントです。「\」が原因でパスが崩れていないかチェックしましょう。スラッシュに変えて試してみるのが有効な手段です。

さらに、既存ファイルへの追記をしようとしている場合も見直します。エンジンをopenpyxlにしているか確認してください。mode=’a’が正しく設定されているかも重要です。それでもダメな場合は、データの一部だけを出力してみます。最初の5行などを抽出して、データの中身に問題がないか探りましょう。5行だけなら成功するのに全体だと失敗するなら原因は明白です。

おかしな文字」とto_excelエラーの意外な原因

ほぼ間違いなくデータの中に「おかしな文字」が紛れ込んでいます。この順番で見ていくと、私の場合はたいてい途中で原因にたどり着けました。to_excelのエラーは集計コードのせいに見えて、実は保存まわりの単純な設定が原因のことが多かったです。同じところで止まっている方の、確認の手がかりになれば嬉しいです。

関連リンクとチェックリスト

学習サービスとアンケート