pandas의 read_excel()이 오류 없이 실행됐는데 데이터가 비어 보이거나 열 이름이 어긋난다면, 파일이 고장 났다고 단정하기보다 시트와 상단 행을 먼저 확인해야 합니다. 핵심은 시트 선택을 확인한 뒤 원본 행을 미리 보고 header, skiprows, usecols를 하나씩 맞추는 것입니다.
먼저 시트 선택부터 확인합니다
read_excel()은 sheet_name을 생략하면 첫 번째 시트를 읽습니다. 파일 안에 여러 시트가 있다면 원하는 시트가 아니라 첫 번째 시트를 읽고도 정상 실행될 수 있으므로, 결과가 비어 보일 때는 시트 이름부터 확인하는 편이 안전합니다.
import pandas as pd
path = "input.xlsx"
excel = pd.ExcelFile(path)
print(excel.sheet_names)
df = pd.read_excel(path, sheet_name="매출")
print(df.shape)
print(df.head())
문자열은 시트 이름으로, 정수는 시트 위치로 해석됩니다. 위치를 사용할 때는 0부터 세므로 sheet_name=0은 첫 번째 시트입니다. 운영 파일처럼 시트 순서가 바뀔 수 있는 경우에는 실제 이름을 확인한 뒤 이름으로 지정하는 방식이 읽기 쉽습니다.
시트 이름을 아직 모른다면 모든 시트를 사전 형태로 받아 구조를 비교할 수도 있습니다.
all_sheets = pd.read_excel(path, sheet_name=None)
for name, frame in all_sheets.items():
print(name, frame.shape)
이 단계에서는 시트별 행·열 크기를 비교해 확인할 시트를 좁힙니다. 내용까지 비교하려면 각 데이터프레임의 head()도 출력해 보세요.
상단 행을 헤더로 오해하지 않았는지 봅니다
엑셀 문서에는 보고서 제목, 작성 기준일, 설명 문장이 실제 열 이름보다 위에 놓이는 경우가 있습니다. 이때 기본 설정으로 읽으면 설명 행이 열 이름이 되고, 실제 헤더 아래의 값이 엉뚱한 열에 들어간 것처럼 보일 수 있습니다.
먼저 헤더를 정하지 않고 상단 행을 그대로 확인합니다.
다음 코드는 매출 시트의 상단 8행을 살펴보는 가상 예시입니다.
preview = pd.read_excel(path, sheet_name="매출", header=None, nrows=8)
print(preview)
미리보기에서 거래일, 상품명, 금액처럼 실제 열 이름이 있는 행의 위치를 찾습니다. 그 행을 헤더로 쓸 수 있다면 해당 0-based 행 번호를 header에 지정합니다.
아래 예시는 원본에서 세 번째 행이 열 이름인 경우이며, header=2의 숫자는 0부터 센 위치입니다.
df = pd.read_excel(path, sheet_name="매출", header=2)
print(df.columns.tolist())
제목이나 설명 행을 건너뛰는 목적이라면 skiprows를 사용할 수 있습니다. 다만 header와 skiprows를 함께 바꾸면 실제로 헤더가 어느 행으로 해석되는지 다시 확인해야 합니다.
아래 예시는 맨 위 2행을 건너뛴 뒤 다음 행을 헤더로 읽는 경우입니다.
df = pd.read_excel(path, sheet_name="매출", skiprows=2)
print(df.head())
두 설정의 판단 기준은 간단합니다. 실제 열 이름이 있는 행을 그대로 열 이름으로 사용할 때는 header, 시작 부분의 불필요한 행을 제외한 뒤 남은 표를 읽을 때는 skiprows를 우선 검토합니다. 설명 행을 데이터로 보존해야 한다면 header=None으로 읽은 뒤 필요한 행을 코드에서 별도로 처리하는 편이 낫습니다.
열을 줄였다면 usecols를 마지막에 검증합니다
시트와 헤더가 맞는데도 특정 열이 빠진다면 usecols를 확인합니다. 이 옵션은 Excel 열 범위, 열 위치 목록, 열 이름 목록 등으로 읽을 범위를 제한할 수 있습니다.
다음 가상 예시는 세 번째 행을 헤더로 사용하고 Excel의 A열부터 D열까지 선택합니다.
df = pd.read_excel(path, sheet_name="매출", header=2, usecols="A:D")
print(df.columns.tolist())
열 이름을 기준으로 제한할 때는 먼저 헤더가 기대한 이름으로 만들어졌는지 확인해야 합니다. 헤더가 설명 행으로 잘못 잡힌 상태에서 usecols를 적용하면, 열 선택 문제처럼 보이지만 실제 원인은 앞 단계에 있을 수 있습니다.
저라면 다음 순서로 좁힙니다.
ExcelFile(path).sheet_names로 실제 시트 목록을 출력합니다.header=None으로 상단 행을 출력해 제목·설명·헤더의 위치를 구분합니다.- 시트 이름과
header또는skiprows중 필요한 설정만 적용합니다. columns,shape,head()로 읽은 구조를 확인한 뒤usecols를 추가합니다.
예제의 시트 이름과 행 위치는 실제 파일에 맞게 바꾸고, 설정을 바꿀 때마다 출력된 열 이름과 상단 값을 원본과 비교하세요. 여러 설정을 한 번에 바꾸지 않으면 어느 설정이 결과에 영향을 주었는지 살피기 쉽습니다. 특히 행이 없는 결과가 나왔다는 이유만으로 원본 파일을 수정하기 전에, 선택한 시트와 헤더 행이 실제 표와 맞는지부터 확인하는 것이 좋습니다.
그래도 읽히지 않을 때의 보조 분기
위 확인 뒤에도 파일을 열지 못한다면 그때 경로와 파일 형식을 봅니다. 경로가 현재 실행 위치에서 실제 파일을 가리키는지, 확장자와 파일 형식이 일치하는지 확인하고, xlsx·xlsm 파일에서 사용하는 엔진 의존성 오류인지 구분합니다. 이 분기는 데이터가 비어 보이는 구조 문제와 달리, 파일을 여는 단계에서 예외가 발생하는 경우에 해당합니다.
따라서 오류 없이 결과가 나왔는데 내용만 이상한 경우에는 패키지 설치부터 반복하기보다 시트와 행 구조를 먼저 진단하는 편이 효율적입니다.
정리
read_excel() 결과가 비어 보이거나 열이 어긋날 때의 기준은 “파일이 정상인가”를 바로 판단하는 것이 아니라 “어떤 시트의 어느 행을 표의 시작으로 읽었는가”를 확인하는 것입니다. 시트 목록과 상단 행을 먼저 확인하고, header·skiprows를 맞춘 뒤, 마지막에 usecols를 제한하면 원인과 수정 범위를 분리할 수 있습니다.