pandasで列を指定するとKeyErrorが出る原因と対処法を試した話

pandasで列を指定したら「KeyError」で止まる。画面のExcelやCSVには、確かにその列名が並んでいるのにです。私はプログラミングのプの字も知らない事務職からの独学なので、「ちゃんとあるのに何で？」とずいぶん長いこと悩みました。

ただ、何度も同じところで止まるうちに、KeyErrorが出る原因はだいたい決まっていると気づきました。人間には同じ文字に見えていても、Pythonから見ると別物になっている「見えない何か」が、たいてい列名に紛れ込んでいるのです。

ここでは、私が実際につまずいたKeyErrorの原因と、そのとき試したことを順番に共有します。同じところで止まっている方の、確認の手がかりになればと思って書きました。

KeyErrorとの格闘、解決の糸口

はじめてこのエラーを見たとき、私は自分の目を疑いました。画面に表示されたDataFrameを確認します。指定したはずの列名は確かに存在していたからです。しかし、何度コードを修正してもエラーは消えません。プログラムは無情にも「KeyError」を吐き出します。そして、そこで処理が止まってしまいました。実は、このエラーが示す事実は非常にシンプルです。「指定した名前が列のリストの中に存在しない」ということです。

当時の私はその事実を受け入れられませんでした。なぜなら、元データであるExcelファイルを開いて確認したからです。そこには一文字の間違いもなく正しい項目名がありました。結局、どこに間違いがあるのか分かりません。変数名を書き換えたり、ファイルの読み込み設定をいじったりしました。そうしているうちに、気がつけば1時間が経過していました。

KeyError解決の第一歩：データ認識

最終的には、その場しのぎの修正ではどうにもなりません。原因を論理的に切り分ける必要性に気づきました。コンピュータは私たちの期待通りには動きません。書かれたコードの通りにしか動いてくれないのです。見た目上の「正解」に惑わされず、プログラムがデータをどう認識しているかを先に確かめる。これが、私がたどり着いたKeyError解決の第一歩でした。次の章からは、その確認のやり方を具体的に見ていきます。

列名に潜む見えない文字の発見

まずは、自分の思い込みを捨てることから始めました。画面に表示されている表形式の結果には注意が必要です。これはあくまで人間が見やすいように整形されたものです。実際のデータとしてどんな文字列が格納されているか確認してみましょう。なるべく生に近い形で確認することにしたのです。そこで活用したのが「df.columns.tolist()」という命令でした。これは非常に便利なコマンドです。

実際にこのコマンドを実行してみて、衝撃を受けました。思いがけない結果が返ってきたからです。一見すると「売上額」という3文字の列名だと思っていました。しかし実は「 売上額 」のようになっていたのです。前後に何か余分な文字が含まれていました。このように、リスト形式で出力させてみましょう。余計な空白や目に見えない制御文字の存在が浮き彫りになります。

列名確認の習慣化とrepr活用によるエラー激減

それ以来、読み込み後には必ずこの確認を挟むようにしました。人間の目は驚くほど曖昧なので、プログラムが認識している正確な名前を見るのが鉄則だと感じています。この習慣だけで、原因不明のエラーに悩まされることが劇的に減りました。ちなみに、目で見て分かりにくいときは、print([repr(c) for c in df.columns]) という書き方も役に立ちました。repr付きで出すと、空白や特殊な文字が記号として表示されるので、見えない文字をあぶり出せます。私は「列名で迷ったら、まずtolistかreprで生の名前を見る」を口ぐせのようにしてきました。

空白文字によるKeyErrorとその対処法

原因を調査していく中で、最も頻繁に遭遇した犯人がいます。それは「空白文字」でした。CSVファイルを書き出したシステムに原因があることもあります。手入力されたExcelデータのセルに問題があるケースも少なくありません。半角スペースがいつの間にか入り込んでいたのです。人間にとって「売上」と「 売上 」は同じ意味を持つでしょう。しかし、Pythonにとっては全くの別物です。この僅かな違いが、KeyErrorを引き起こす最大の要因でした。

あるプロジェクトで何十個ものファイルを一括処理しました。その際に、特定のファイルだけがエラーで止まってしまいます。詳しく調べたところ、特定の列名の末尾にスペースがありました。そこで解決策として導入したのが魔法の一行です。読み込んだ列名そのものに str.strip() をかけて、前後の空白を一括で取り除く処理でした。これを入れておくと、列名の余分なスペースをまとめて落とせます。

列名スペースの罠、2時間の苦闘と安定化

画面上は同じ日本語の列名に見えるのにエラーが消えません。列名の前後に半角スペースが紛れ込んでいたと気づいたときの脱力感は凄まじいです。一文字を消すために2時間もコードを見直しました。情けなさと安堵が混ざった複雑な気持ちになります。

この処理を読み込み直後に実行するようにしました。それからは、データの作成者に左右されなくなります。安定してプログラムを動かせるようになりました。

全角スペース・大文字小文字の厳密な扱い

空白以外にも、文字の細かな差異が牙を剥くことがあります。特に日本語環境で仕事をしていると避けられない問題に直面します。それが「全角スペース」の混入です。半角スペースなら先ほどのstripメソッドで除去しやすいでしょう。しかし、全角スペースが混じると判別はさらに困難になります。また、アルファベットの「大文字と小文字」にも注意してください。pandasはこれらを厳密に区別して処理を行います。

例えば、「Customer_ID」という列名を指定したとします。元データの項目名が「Customer_Id」になっていたとしましょう。これだけで、処理はエラーになってしまいます。人間なら文脈で読み取れる些細な綴りの違いでも、プログラムにとっては別物の不一致になります。文字を厳密に比較しているので、一文字でも違えば「その列はない」と判断されてしまうのです。

データ前処理：列名統一とBOM問題

そこで私は、列名を扱う際に統一的なルールを当てることにしました。具体的には、列名に str.strip() をかけて前後の空白を取り、続けて str.replace(‘　’, ”) で全角スペースも消すようにしています。大文字小文字がばらつくデータなら、すべて小文字にそろえる str.lower() を通してから指定するのも有効でした。このように、読み込んだ直後にデータの揺らぎをあらかじめ整えておくようにしたのです。作成者によって列名の書き方が違っても、同じコードで処理できるようになりました。

本質的ではないエラーに無駄な時間を奪われるリスクを、最小限に抑えられたと感じています。

非常に厄介だったのが「BOM（Byte Order Mark）」の問題でした。これはCSVファイルを読み込んだ際に発生します。ファイルがUTF-8形式であることを示す特殊なデータです。WindowsのExcelなどで保存されたCSVに注意してください。このBOMが勝手に付与されてしまうのです。これを含んだまま読み込むと問題を引き起こしかねません。先頭の列名の前に「\ufeff」という見えない文字が付くのです。

BOMが招くKeyError、pandasで解消

CSVをExcelで保存し直して読み込みました。すると先頭の日本語列名だけKeyErrorになりました。原因がBOMだと分かるまで遠回りした経験を持っています。列名をコピーしてコードに貼り付けても解決しませんでした。エンコードの仕様にたどり着いたときはパズルを解いた感覚です。

この問題の解決策は、ファイルを読み込む際の設定にあります。「encoding=’utf-8-sig’」というオプションを指定しましょう。これだけで、pandasは先頭のBOMを自動的に取り除いてくれます。純粋な列名だけを取得できるというわけです。実は、この指定を知るまでは全く理解できませんでした。なぜ最初の列だけが常にエラーになるのか不思議に思ったものです。ファイル自体の破損を疑ったこともありました。

ところが、この一行を追加しただけで状況は一変しました。

merge列名重複によるKeyError

複数の表を一つにまとめる「merge」機能は非常に強力です。しかし、ここにもKeyErrorの罠が潜んでいます。結合する2つの表に同じ名前の列が存在するとしましょう。pandasはそれらを区別するためにサフィックスを付与します。列名の末尾に「_x」や「_y」と自動的に追加されるのです。この仕様に気づかないまま、元の列名でアクセスしてみましょう。すると、当然ながらエラーが発生してしまいます。

マージ後の列名変更、確認の習慣化

2つの表をmergeしたあとに列名が勝手に変わりました。元の日本語列名で指定してKeyErrorを出していた話です。結合した安心感で結果を確認しませんでした。その後の処理で突然止まった理由がわからず途方に暮れました。小一時間コードと睨めっこしていた苦い思い出です。

具体的には、結合後に「金額」という列を使おうとしました。しかし実際には「金額_x」になっていたのです。そのため見つからないと言われてしまいました。これを防ぐには、mergeを実行する際に名前を指定します。「suffixes=(‘_left’, ‘_right’)」と設定しましょう。あるいは、結合後に明示的に列名をリネームする必要があります。

そこで私は、結合処理の直後に必ず列名を確認するようにしました。自分が意図した通りの名前で列が残っているかチェックします。逐一確認することが何よりも重要です。

KeyError解決の第一歩：列名確認

最後に、KeyErrorに遭遇した際の解決フローをまとめました。まずはパニックにならず、原因を一つずつ潰していきましょう。第一に「df.columns.tolist()」を実行します。プログラムが認識している正確な列名のリストを取得します。自分の目でしっかりと確認することから始めましょう。

次に、その出力結果を見て細かい部分をチェックします。列名の前後に不自然な空白や記号が含まれていないか探してみてください。もし含まれている場合は、迷わずstripメソッドを使いましょう。一括削除して綺麗な状態にします。さらに、全角と半角の混在や大文字小文字のミスがないか精査しましょう。実は、これらを確認するだけで大半は解決に近づきます。KeyErrorの8割以上は防げるといっても過言ではありません。

この前半の確認だけで、私の場合は大半の原因にたどり着けました。

データ処理エラー解消のチェックリスト

前半で見つからないときは、CSV読み込み時のBOMの影響も考えます。先頭の列だけがエラーになるときは、encoding=’utf-8-sig’ を試すと一発で直ることが多かったです。結合後のサフィックス付与についても、同じようにチェックしてください。mergeを使った直後は、もう一度 df.columns.tolist() で名前を見ておくと安心でした。該当する処理があるなら、必ずそこを疑うようにしています。エラーを「よく分からない魔法」のように恐れず、原因に基づいたチェックリストとして淡々と当たっていく。

これが、遠回りを減らすうえで一番効いた考え方でした。

実は、どうしても列が存在しない可能性もあります。そんなときは「df.get(‘列名’, デフォルト値)」を使ってみてください。このメソッドを使うのも効果的な一つの手です。これなら、万が一列が見つからなくても処理は止まりません。KeyErrorを回避しつつ、指定した値を返してくれます。同じところで止まっている方の、確認の手がかりになれば嬉しいです。

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

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