Bỏ qua đến nội dung chính
Mục lục

KeyError khi chọn cột pandas: tên sai, khoảng trắng, BOM

AIDev Team · duyệt: Nguyễn Việt Chung

Bài 1/13 · Chương 10

Giải nghĩa lỗi và cảnh báo

  • 7 phút
  • Cơ bản
  • Python 3.14
  • Cập nhật

Thông báo KeyError: 'Tỉnh' khi chọn cột trong pandas nghĩa là bảng không có cột nào mang đúng cái tên bạn vừa gõ, từng ký tự một. Lỗi hay đến từ một tên gần đúng: khác chữ hoa, thiếu dấu, dư một khoảng trắng, hay dính ký tự BOM mà Excel ghi ở đầu file CSV.

Cần biết trước: chọn cột trong pandas và DataFrame.

Bảng tra nhanh: nguyên nhân KeyError khi chọn cột

Python gọi lỗi này là KeyError, cùng lớp lỗi với tra một khóa không có trong dict. Phần sau dấu hai chấm là đúng tên bạn đã gõ; tên thật trong bảng phải tự in ra mới thấy.

Phần sau KeyError:

Nguyên nhân

Cách sửa

'Tỉnh'

gõ khác tên cột: chữ hoa, có dấu

gõ đúng "tinh" như df.columns in ra

'tinh'

tên cột trong file là ' tinh', dư khoảng trắng

bỏ khoảng trắng hai đầu tên cột

'ma_kh'

tên cột đầu dính BOM thành 'ma_kh'

đọc lại với encoding="utf-8-sig"

"['tinh '] not in index"

một tên trong list cột không có

sửa tên đó; thông báo kể đủ các tên thiếu

Việc đầu tiên khi gặp lỗi này là in tên thật của các cột. df.columns.to_list() in từng tên trong nháy đơn, nên khoảng trắng và ký tự lạ hiện ra rõ:

python
import pandas as pd

kh = pd.read_csv("khach_hang.csv")
print(kh.shape)
print(kh.columns.to_list())
print(kh[["ma_kh", "tinh"]].head(3))

KẾT QUẢ

(400, 6)
['ma_kh', 'ho_ten', 'gioi_tinh', 'nam_sinh', 'tinh', 'ngay_dang_ky']
    ma_kh     tinh
0  KH0001   Hà Nội
1  KH0002  Cần Thơ
2  KH0003   Hà Nội

Bảng khách có 400 dòng và sáu cột, tên viết thường, không dấu. Đổi "tinh" thành "Tinh" rồi chạy lại: chương trình dừng và in ['Tinh'] not in index, vì list cột có một tên không khớp.

Tên gõ khác tên trong bảng

pandas so tên cột như so khóa của dict: "Tỉnh", "Tinh" và "tinh" là ba tên khác nhau. Gõ tên theo cách bạn đọc tiêu đề trong Excel là nguyên nhân hay gặp:

python
import pandas as pd

kh = pd.read_csv("khach_hang.csv")
print(kh["Tỉnh"].head(3))

Dòng cuối của thông báo lỗi:

text
KeyError: 'Tỉnh'

Khi bảng có nhiều cột, so tên bằng mắt dễ sót. Hỏi thẳng bằng in, hay lọc các tên gần giống bằng một list comprehension:

python
import pandas as pd

kh = pd.DataFrame({"ma_kh": ["KH0001"], "tinh": ["Huế"]})
print("Tinh" in kh.columns, "tinh" in kh.columns)
print([ten for ten in kh.columns if ten.lower() == "tinh"])

KẾT QUẢ

False True
['tinh']

in kh.columns trả lời đúng câu "có cột tên này không", giống in trên các khóa của dict.

Khoảng trắng thừa trong tên cột

File CSV gõ tay hay xuất từ phần mềm cũ hay có dấu cách sau dấu phẩy: ma_kh, tinh. pandas giữ nguyên dấu cách đó, nên cột thứ hai tên là ' tinh':

python
import io
import pandas as pd

csv = "ma_kh, tinh\nKH0001, Huế\nKH0002, Đà Lạt\n"
kh = pd.read_csv(io.StringIO(csv))
print(kh["tinh"])

Dòng cuối của thông báo lỗi:

text
KeyError: 'tinh'

Thông báo in 'tinh' nên trông như cột có thật. Chỉ khi in kh.columns.to_list() bạn mới thấy dấu cách đứng trước. Sửa bằng cách gán lại columns từ các tên đã bỏ khoảng trắng hai đầu:

python
import io
import pandas as pd

csv = "ma_kh, tinh\nKH0001, Huế\nKH0002, Đà Lạt\n"
kh = pd.read_csv(io.StringIO(csv))
print(kh.columns.to_list())
kh.columns = [ten.strip() for ten in kh.columns]
print(kh["tinh"].to_list())

KẾT QUẢ

['ma_kh', ' tinh']
[' Huế', ' Đà Lạt']

Giá trị trong cột cũng mang dấu cách đầu (' Huế'). Tham số skipinitialspace=True của read_csv() bỏ dấu cách sau mỗi dấu phẩy, ở cả tên cột lẫn giá trị.

Ký tự BOM dính vào tên cột đầu

Excel lưu "CSV UTF-8" bằng ba byte đánh dấu ở đầu file, gọi là BOM. read_csv() với bảng mã mặc định UTF-8 tự bỏ ba byte này. Nhưng nếu bạn đọc file đó bằng một bảng mã khác, như cp1258 của Windows, ba byte thành ba ký tự lạ và dính vào tên cột đầu:

python
from pathlib import Path
import pandas as pd

Path("kh_excel.csv").write_text("ma_kh,tinh\nKH0001,Huế\n",
                                encoding="utf-8-sig")
kh = pd.read_csv("kh_excel.csv", encoding="cp1258")
print(kh.columns.to_list())
kh = pd.read_csv("kh_excel.csv", encoding="utf-8-sig")
print(kh.columns.to_list(), kh["tinh"].to_list())

KẾT QUẢ

['ma_kh', 'tinh']
['ma_kh', 'tinh'] ['Huế']

Với lần đọc đầu, kh["ma_kh"] báo KeyError với tên 'ma_kh' dù cột ấy "có" trong bảng. utf-8-sig đọc được cả file có BOM lẫn file không có. BOM và bảng mã được giải thích ở bài mã hóa UTF-8 trong Python.

Chọn nhiều cột một lần

Khi chọn bằng một list tên, thông báo không in một tên mà kể mọi tên không tìm thấy, trong một list:

Dấu nháy quanh 'tinh ' cho thấy khoảng trắng nằm trong tên bạn gõ, không nằm trong bảng.

Kiểm tra nhanh

  1. Sau import pandas as pd và bang = pd.DataFrame({"tinh": ["Huế"]}), bang["Tinh"] báo lỗi gì?

    • Báo lỗi AttributeError
    • Báo lỗi KeyError
    • Báo lỗi TypeError
  2. Bảng kh có kh.columns.to_list() là ['ma_kh', ' tinh']. Những lệnh nào báo KeyError?

    • kh["tinh"]
    • kh[" tinh"]
    • kh[["ma_kh", "tinh"]]
    • kh["ma_kh"]
  3. Trong ví dụ BOM, vì sao lần đọc bằng cp1258 cho tên cột đầu là 'ma_kh'?

    • File không có cột ma_kh
    • Ba byte BOM ở đầu file được đọc thành ba ký tự và dính vào tên cột đầu
    • cp1258 đổi mọi tên cột sang chữ khác
Đúng hết lần đầu +15 XP

Bài tập

Làm sạch tên cột trước khi chọn

Bảng khách nhận từ nhiều nơi có tên cột lộn xộn: ký tự BOM "\ufeff" ở đầu tên, khoảng trắng ở hai đầu, chữ hoa. Viết thân hàm lam_sach_ten_cot(bang): trả về một bảng mới giống bang, trừ tên mỗi cột đã được bỏ ký tự "\ufeff", bỏ khoảng trắng hai đầu, rồi đổi thành chữ thường. Dấu cách ở giữa tên giữ nguyên.

Bảng mới giữ mọi dòng, giá trị, thứ tự cột và index. Hàm không sửa bảng bang của nơi gọi.

Trả về: bảng có tên cột đã làm sạch, một DataFrame.

python
import pandas as pd

def lam_sach_ten_cot(bang):
    pass  # Viết thân hàm thay cho dòng này

Tóm tắt

  • KeyError khi chọn cột in đúng tên bạn gõ; bảng không có cột nào trùng tên đó từng ký tự.

  • In df.columns.to_list() để thấy tên thật trong nháy đơn, kể cả khoảng trắng và ký tự lạ.

  • Tên cột có dấu cách đầu hay cuối: gán lại df.columns từ các tên đã strip(), hoặc đọc với skipinitialspace=True.

  • '' ở đầu tên cột đầu là BOM bị đọc sai bảng mã: đọc lại với encoding="utf-8-sig".

  • Chọn bằng list cột thì thông báo kể mọi tên thiếu, dạng "[...] not in index".

  • Gán vào tên cột gõ sai không báo lỗi mà tạo thêm cột mới.

Câu hỏi thường gặp

Vì sao cột có trong file mà pandas báo column not found?

Vì tên trong bảng khác tên bạn gõ ở một chỗ khó thấy: dấu cách thừa, chữ hoa, dấu tiếng Việt, hay BOM ở cột đầu. In df.columns.to_list() và so từng ký tự trong nháy đơn. Cách chọn cột đúng nằm ở bài chọn cột.

Có cách chọn cột mà không báo KeyError không?

Có: df.get("tinh") trả None khi bảng không có cột đó, như get() của dict. Cách này che mất tên gõ sai, nên chỉ dùng khi cột thiếu là chuyện bình thường; còn lại hãy để lỗi báo ra rồi sửa tên.

Sau khi merge, chọn cột cũ thì báo KeyError, vì sao?

Khi hai bảng cùng có một cột không phải khóa, merge() đổi tên chúng thành ten_x và ten_y, nên tên cũ không còn. Bài merge trong pandas nói cách đặt hậu tố bằng suffixes=.

KeyError: 0 khi lấy phần tử đầu của Series nghĩa là gì?

Series có index nhãn chữ thì s[0] tìm nhãn 0 chứ không lấy theo vị trí, và pandas 3 báo KeyError với nhãn 0. Lấy phần tử đầu bằng s.iloc[0], như bài loc và iloc.

Chủ đề

keyerror pandas

Dữ liệu của bài

Bài này có hữu ích?

Hỏi đáp

Đang tải câu hỏi…

Tham vấn chuyên môn

Nguyễn Việt Chung

Nhà sáng lập AIDev và VietPlatform · Thạc sĩ AI MSE

  • Tốt nghiệp thủ khoa xuất sắc Thạc sĩ AI MSE.
  • Đồng sáng lập, CTO E-University, SVOnline: số hóa 10+ đại học, 40.000+ sinh viên.
  • Xây hệ thống AI cho doanh nghiệp tại VietPlatform.
Biên soạn: AIDev Team · Rà soát · Quy trình biên tập