CSV의 열 이름이 코드에서 찾는 이름과 다르면, 파일 첫 줄과 DictReader.fieldnames를 먼저 비교하세요. 이 실습에서는 CSV에 Name이라고 적혀 있는데 코드가 name을 찾습니다. 작은 연습용 파일에서 차이를 확인하고 첫 줄을 고친 뒤, 첫 행의 ‘여울’을 읽는 것까지 해볼게요. 이 코드는 파일을 읽기만 하며 원본 CSV를 수정하지 않습니다.
아래 결과는 2026년 9월 25일 macOS의 Python 3.14.4에서 같은 코드로 직접 실행했습니다. Python의 csv.DictReader 공식 문서에 따르면 별도로 열 이름을 지정하지 않으면 첫 행을 열 이름으로 사용합니다. 따라서 화면에 보이는 헤더를 확인하는 것이 시작점입니다.

연습용 CSV와 확인 코드를 준비하세요
다음 두 줄을 UTF-8 텍스트 파일 sample.csv로 저장하세요. 쉼표와 대문자 N을 그대로 두어야 첫 번째 결과를 재현할 수 있습니다. 개인 정보가 담긴 실제 파일 대신 이 연습용 파일로 시작하세요.
Name,age
여울,2
아래 코드를 같은 폴더의 check_csv.py로 저장하고 그 폴더에서 python3 check_csv.py를 실행하세요. Windows에서 python3 명령이 없다면 설치된 환경의 py check_csv.py 또는 python check_csv.py를 사용합니다. 명령이 인식되지 않는다면 아직 CSV 내용보다 Python 실행 환경을 확인할 단계입니다.
import csv
from pathlib import Path
with Path("sample.csv").open(newline="", encoding="utf-8") as file:
reader = csv.DictReader(file)
headers = reader.fieldnames
first = next(reader, None)
print("열 이름:", headers)
print("첫 행:", first)
if not headers:
print("헤더를 찾지 못했습니다.")
elif first is None:
print("데이터 행이 없습니다.")
elif "name" not in first:
print("name 열이 없습니다. 실제 열 이름을 확인하세요.")
else:
print("name 값:", first["name"])
newline=""는 CSV가 인용부호 안의 줄바꿈을 자체 규칙으로 처리하게 하기 위한 공식 문서의 권장 방식입니다. DictReader는 각 행을 열 이름을 키로 하는 사전으로 반환합니다. 이 코드는 첫 행만 살펴보므로 전체 파일의 오류를 모두 검증하지는 않습니다.
열 이름과 첫 행이 어떻게 다른지 보세요
첫 번째 실행 결과는 다음과 같습니다. Name과 name은 철자가 비슷해도 대소문자가 달라 이 코드에서는 같은 키가 아닙니다. 첫 행의 값 ‘여울’은 읽혔지만, 요청한 name 키가 없어서 안내 문장이 나옵니다.
열 이름: ['Name', 'age']
첫 행: {'Name': '여울', 'age': '2'}
name 열이 없습니다. 실제 열 이름을 확인하세요.
헤더를 보지 않고 바로 first["name"]을 꺼내면 키가 없어 KeyError가 날 수 있습니다. 위 코드는 먼저 키가 있는지 검사해 어디가 다른지 보여줍니다. 오류 메시지의 위치부터 읽어야 한다면 파이썬 오류 메시지의 마지막 줄과 위치를 확인하는 순서로 이어가세요.
연습용 사본의 첫 줄을 고쳐 다시 실행하세요
sample.csv의 첫 줄에서 Name만 name으로 바꾸고 두 번째 줄은 그대로 두세요. 다시 실행하면 다음처럼 열 이름과 첫 행의 키가 같아지고 최종 값 ‘여울’을 읽습니다.
열 이름: ['name', 'age']
첫 행: {'name': '여울', 'age': '2'}
name 값: 여울
이 예제에서 파일을 고친 것은 연습용 CSV입니다. 실제 업무 파일을 수정하기 전에는 원본을 보관하고, 파일의 열 이름을 바꿀지 아니면 자기 코드에서 실제 열 이름을 사용할지 결정하세요. 다른 프로그램이 기존 Name 열을 쓰고 있다면 원본을 고치는 것이 적절하지 않을 수 있습니다.
헤더만 있거나 결과가 다르면 이 부분을 확인하세요
파일이 name,age 한 줄뿐이면 열 이름은 읽혀도 데이터 행은 없어 첫 행: None과 데이터 행이 없습니다.가 나옵니다. 빈 파일에는 헤더도 없으므로 코드는 헤더를 찾지 못했습니다.라고 말합니다. 둘 다 열 이름을 잘못 쓴 경우와 구분해야 합니다.
다른 결과가 나온다면 저장한 파일 이름과 실행 폴더, 첫 줄의 대소문자·앞뒤 공백·쉼표를 차례로 보세요. 예를 들어 name처럼 앞에 공백이 있으면 여기서는 name과 다른 열 이름입니다. 이 글의 코드는 자동으로 공백을 지우거나 모든 열을 교정하지 않습니다.
완료 기준은 수정 전에는 ['Name', 'age']와 열 이름 불일치 안내가, 수정 후에는 ['name', 'age']와 name 값: 여울이 나오는 것입니다. 두 결과가 맞으면 자기 CSV의 복사본에서 실제 헤더를 출력해 비교하세요. 데이터 행이 없거나 파일을 찾지 못하면 열 이름을 고치기 전에 파일 경로와 입력 내용을 먼저 확인하면 됩니다.