pandasのread_csvで「Error tokenizing data」が出たときに、列数のずれたCSVを読み込めた話

Pythonで業務を効率化しようとする方は多いです。そしてpandasのread_csv関数を叩いた経験はありませんか。最初は順調に進んでいたはずです。しかし突然エラーが表示されます。「Error tokenizing data」という文字です。この文字に心臓が止まるような思いをした方も多いでしょう。私は過去に取引先の売上データでこのエラーに遭遇しました。その原因究明に数時間も費やしてしまったのです。実はこのエラーはCSVの形式が期待と異なるときに発生します。特に業務で扱うCSVは一筋縄ではいきません。システム出力や手作業の編集が加わるからです。

なぜエラーが起きるのかを具体的に共有しましょう。どうすれば安全に読み込めるのかを説明します。同じエラーで悩む方の助けになれば幸いです。

pandas CSV読込エラーの正体

初めてこのエラーに出会ったときは驚きました。何が起きているのか全く理解できなかったのです。いつものようにコードを書いて実行ボタンを押しました。それなのに長文のエラーメッセージが表示されます。期待したデータフレームは一行も生成されませんでした。取引先から月次の売上CSVが送られてきたときの話です。pandasで読み込もうとした瞬間にエラーが出ました。「Error tokenizing data」が画面を埋め尽くしたのです。ファイルはテキストエディタで開くと普通に見えます。なぜ読み込めないのか全く分かりませんでした。

その日は結局手作業でコピペして帰宅したのを覚えています。実はファイルが壊れているわけではありません。pandasは読み込む際のルールを内部で決めています。ルールと実際のファイルの中身にズレがあるときに発生します。

エラーの正体と解決の糸口

最初はファイルが破損しているのかと疑いました。何度もダウンロードし直した記憶があります。文字コードを変換してみたりもしました。しかし結果は全く同じ状態だったのです。エラーメッセージをよく見ると行番号がわかります。何行目で何が起きているのか詳しく書かれていました。このエラーメッセージを冷静に読み解きましょう。それが解決への第一歩となります。

エラーメッセージから列数不一致の原因特定

エラーメッセージの記述に注目してください。「Expected N fields…」という部分です。この記述には非常に重要なヒントが隠されています。pandasは「この行にはN個の列があるはず」と予測します。しかし実際に読み込んでみたらM個だったという意味です。例えば10行目のエラー表示を想像しましょう。Expected 5 fields in line 10, saw 6と出たとします。これは10行目にデータが6個あるという意味です。そのためpandasが混乱していることを示します。この数値の確認がとても大切です。

そうすることで原因となる行を特定できます。期待した列数と実際の列数を見比べるだけで、原因の行をかなり絞り込めることが多いです。

CSVエラーの特定と視覚確認

カンマ区切りのCSVを例に考えてみましょう。データの中にカンマが含まれることがあります。また列数が途中で変わっていることも多いです。そのような場面でこのエラーは頻発します。もしこれが起きたらエラーメッセージを確認してください。「line X」の数字を必ずメモしましょう。次にテキストエディタでその行を開いてみます。何が起きているのかが視覚的に分かるはずです。

カンマが原因のCSV列数ズレをPandasで解決

エラーの原因として最も多いのは列数の問題です。CSV内の列数が一定ではないことがあります。通常はすべての行で列数が一致している必要があります。しかし業務で使われるCSVはそうとは限りません。例えば備考欄に自由に文章を入力できる場合です。その文章の中にカンマが含まれていることがあります。するとpandasはそこを列の区切りと誤解してしまいます。私が過去にエラー行をテキストエディタで開いたときの話です。備考欄にカンマ入りの文字列が含まれていました。「2023年10月, 修正済み」のような文章です。これが原因で列数が1つ増えていたのです。

pandasが「列数が違う」と判断して止まっていました。このような場合データを正しく把握できなくなります。そしてそのまま読み込みを中断してしまうのです。もし列数が物理的に違うならデータを見直す必要があります。単純な不備ならエディタで修正して保存し直せば解決します。

pandasの列ズレ対応で作業効率化

しかしデータ量が数万行ある場合もあります。そのすべてを手作業で直すのは不可能です。そのためpandas側で列のズレの扱いを指定します。列数がバラバラなファイルでも機械的に読み込めます。そのような設定があることをぜひ知っておいてください。そうすれば作業の幅が大きく広がるでしょう。

CSV読み込みの区切り文字とオプション

次に疑うべきはCSVの区切り文字です。read_csvは既定でカンマを区切り文字として扱います。しかし実際にはタブ区切りのファイルも存在します。セミコロンで区切られたデータも珍しくありません。データ内に予期せぬカンマが混入していることもあります。その場合も区切り文字を工夫すれば解決可能です。たとえばタブ区切りなら「sep=’\t’」と指定します。データ内にカンマが多用されている場合も同様です。区切り文字を別の記号に変更して保存し直す手もあります。または読み込み時の工夫が必要です。正しく指定できればエラーの解消確率は高まります。

実は引用符で囲まれたカンマもよくあるケースです。その場合pandasは自動的にそれを処理してくれます。しかし引用符が正しく閉じていないと厄介です。エラーがどんどん連鎖してしまいます。そのようなケースではオプションを指定しましょう。engine=’python’というオプションが便利です。柔軟な読み込みを行うのも有効な手段となります。

処理速度の遅延と利用上の注意点

ただしこのオプションには速度が遅くなる欠点があります。標準のCエンジンよりも読み込みに時間がかかるのです。小規模なファイルなら特に問題ありません。しかし数百万行あるような巨大なCSVには不向きです。まずは標準のエンジンで解決できないかを試してください。

CSV列数バラバラ問題：names引数で構造定義

列数がバラバラなCSVを読み込む際にもコツがあります。names引数で列名を明示的に指定する方法です。これに列名のリストを渡してみましょう。するとpandasはその列数を基準に読み込もうとします。もし列数が足りない行があったとしても大丈夫です。指定した列数に合うように調整してくれる場合があります。データフレームの構造を強制的に定義する感覚に近いです。列数がまちまちで読み込めない売上CSVがありました。そのとき私はデータに含まれる最大の列数を数えました。そしてnames引数で列名を定義してみたのです。すると列数の足りない行を空のまま読み込んでくれました。

エラーで止まることがなくなったという実体験があります。この方法の利点は処理の完全な停止を防げることです。ただし列数が多すぎる行がある場合は注意が必要です。その場合はやはり別の対策が求められます。あくまで列数が足りないエラーに有効な手段となります。ぜひこの解決策を覚えておくとよいでしょう。

Pandasによる不良行スキップと注意点

どうしても読み込めない壊れた行があるかもしれません。それが一部だけならその行を無視するのが賢い選択です。pandas 1.3以降なら便利なオプションがあります。「on_bad_lines=’skip’」を使ってみてください。列数が合わない行を自動的に読み飛ばすことができます。これを使えばエラーで処理全体が止まるのを防げます。そして読み込めるデータだけを抽出できるのです。古いバージョンでは「error_bad_lines=False」でした。しかし最新版ではon_bad_linesを使うのが一般的です。

この方法は非常に強力ですが注意点もあります。読み飛ばされた行に重要なデータが含まれる場合です。その場合は分析結果に影響が出るかもしれません。そのためskipした行の数を確認しておくことは大切です。飛ばされた行が思ったより多いと感じたときは、中身を見直しましょう。どの行が飛ばされたのかも必ずチェックしてください。

skiprowsによるCSV不要行対策

システムから出力されたCSVを思い浮かべてください。データの前に作成日や対象期間が含まれることが多いです。これらは不要な説明行と言えるでしょう。これが原因で列数が判定できずにエラーになることもあります。そんなときはskiprowsを使ってみてください。このオプションで先頭の不要な行を読み飛ばせます。例えば最初の3行が不要だとしましょう。その場合は「skiprows=3」と指定するだけです。これだけでデータの本体から読み込みを始めてくれます。データフレームのヘッダーが正しい行から始まるようになります。このように調整するだけでエラーが消えることは多いです。

データが複雑な形式のファイルもあるでしょう。先頭行以外にも不要な箇所があるかもしれません。その場合はskiprowsにリストを渡すことができます。そうすれば特定の行だけを飛ばすことも可能です。まずはCSVファイルを一度開いてみましょう。どの行からデータが始まっているのかを確認する癖が大切です。

Pandasエラー解決と未来の効率化

最後にこのエラーに遭遇したときの手順を整理します。まずメッセージを見て何行目に問題があるかを確認してください。次にその行をテキストエディタで直接開きます。カンマの混入や列数のズレがないかを見てみましょう。もし列数がバラバラならon_bad_linesを試します。区切り文字が怪しければsep引数で明示してください。先頭に不要な行があるならskiprowsで飛ばしましょう。それでもダメならnamesで列数を固定する手もあります。最初は英語のメッセージに圧倒されるかもしれません。しかし一つずつ切り分けて確認すれば必ず解決できます。

pandasは非常に強力で便利なツールです。エラーを乗り越えるたびに知識が深まっていくはずです。焦らず落ち着いて一つずつ設定を見直してみましょう。今まで手作業で苦労していた集計作業があるかもしれません。しかし驚くほど楽になる日がきっと来るはずです。

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

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