엑셀이나 CSV를 읽은 뒤 df['매출액']에서 KeyError가 난다면, 화면에 보이는 제목과 실제 column label이 다를 가능성이 큽니다. 먼저 df.columns를 repr()로 확인해 앞뒤 공백과 실제 문자를 드러낸 뒤, 공통으로 안전한 차이면 정규화하고 명칭 계약이 다르면 명시적으로 매핑해야 합니다.
화면에 열이 있는데도 KeyError가 나는 이유
pandas에서 열 이름은 DataFrame의 Index에 들어 있는 label입니다. 사람이 표에서 읽는 모양이 같아 보여도 실제 label에 뒤 공백이 있거나, 대소문자·전각/반각처럼 다른 문자가 섞이면 df['매출액']와 일치하지 않습니다.
처음부터 열을 새로 만들거나 pandas를 재설치하기보다, 현재 DataFrame이 가진 label을 그대로 확인하는 편이 빠릅니다.
import pandas as pd
df = pd.read_csv("sales.csv")
print(df.columns)
for column in df.columns:
print(repr(column))
repr()은 문자열의 표현을 보여 주므로 눈에 잘 띄지 않는 공백이나 이스케이프 문자를 진단할 때 유용합니다. 예를 들어 출력이 '매출액 '이라면 대괄호 안에 넣어 찾는 이름과 실제 label 사이에 공백이 있는 것입니다.
확인 결과에 따라 조치를 나누기
진단 결과는 세 가지로 나누어 판단하면 됩니다.
첫째, 여러 입력에서 반복되는 앞뒤 공백처럼 같은 규칙으로 제거해도 의미가 바뀌지 않는 차이라면 열 label을 정규화할 수 있습니다.
df.columns = df.columns.str.strip()
매출 = df["매출액"]
df.columns는 Index이므로 문자열 메서드를 적용하는 .str 접근자를 사용할 수 있습니다. str.strip()은 각 label의 앞뒤 공백을 제거합니다. 다만 이 코드는 앞뒤 공백을 없애는 동작일 뿐, 대소문자나 서로 비슷해 보이는 유니코드 문자를 같은 것으로 바꾸는 규칙까지 자동으로 정해 주지는 않습니다.
둘째, 원천 데이터의 명칭을 우리 프로그램의 표준 이름으로 바꾸는 계약이 있다면 rename()으로 매핑을 명시합니다.
df = df.rename(columns={
"매출액(원)": "매출액",
"거래일자": "주문일자",
})
매출 = df["매출액"]
명시적 매핑은 어떤 원천 이름을 어떤 표준 이름으로 바꾸는지 코드에 남긴다는 장점이 있습니다. 매핑에 없는 label은 그대로 유지되므로, 입력 양식이 여러 가지라면 허용할 원천 이름을 문서화해 두는 편이 좋습니다. 존재하지 않는 이름을 반드시 찾아야 하는 상황에서는 errors='raise'를 검토할 수 있지만, 이 옵션 자체가 입력 계약을 대신해 주는 것은 아닙니다.
셋째, 공백을 제거해도 원하는 label이 없거나 의미가 다른 이름이라면 필수 열 누락으로 처리해야 합니다. 이 경우 없는 열을 빈 열로 만들어 흐름을 계속하면 잘못된 결과가 저장될 수 있습니다.
required = {"매출액", "주문일자"}
missing = required.difference(df.columns)
if missing:
raise ValueError(f"필수 열이 없습니다: {sorted(missing)}")
운영 자동화에서는 이 검증을 실제 계산이나 파일 저장보다 앞에 두는 것이 중요합니다. 입력이 잘못되었다는 사실을 조기에 알리고, 원본 파일과 함께 실제 repr() 출력 또는 누락 목록을 로그에 남기면 다음 입력 양식을 고치는 사람도 원인을 추적할 수 있습니다.
자동화 입력에 적용할 때의 순서
저라면 다음 순서로 좁혀 갑니다.
- DataFrame을 읽은 직후
df.columns와 각 label의repr()을 확인합니다. - 모든 입력에 공통으로 적용해도 의미가 보존되는 앞뒤 공백만 정규화합니다.
- 원천 명칭과 표준 명칭이 다른 경우에는
rename()매핑을 코드로 남깁니다. - 표준화가 끝난 뒤 필수 열 집합을 검사합니다.
- 누락이 있으면 계산·저장 전에 중단하고 실제 label과 누락 목록을 기록합니다.
이 순서를 지키면 “오타인가, 공백인가, 입력 계약이 바뀐 것인가”를 한 번에 섞어 처리하지 않게 됩니다. 특히 전각·반각처럼 눈으로 구분하기 어려운 차이는 repr()로 확인한 다음, 업무 데이터의 규칙을 정하고 별도의 변환을 명시하는 편이 안전합니다.
정리
파이썬 pandas에서 열 이름이 분명히 보이는데 KeyError가 난다면 df.columns를 repr()로 출력해 실제 label부터 확인하십시오. 앞뒤 공백처럼 안전하게 통일할 수 있는 차이는 df.columns.str.strip()으로 정리하고, 이름의 의미를 바꾸는 경우는 rename() 매핑으로 남기며, 끝까지 필요한 열이 없으면 처리 전에 중단해야 합니다.
다음 자동화 단계에서는 여러 CSV의 열 이름을 같은 기준으로 맞출지, 필수 열 검증을 별도 함수로 분리할지 결정하면 됩니다. 그 결정은 단순한 문자열 정리가 아니라 해당 데이터가 지켜야 할 입력 계약의 문제입니다.