파이썬 에러 메시지별 해결 방법 총정리

---

---

파이썬 에러 메시지별 해결 방법 총정리

파이썬을 처음 배우는 과정이든, 실무에서 사용하는 상황이든 에러 메시지는 반드시 마주치게 됩니다.
문제는 에러가 발생했다는 사실 자체가 아니라, 에러 메시지를 어떻게 해석하고 해결하느냐입니다.

이 글은 파이썬 사용 중 가장 자주 발생하는 에러 메시지들을 종류별로 정리하고,
각 에러가 왜 발생하는지, 그리고 어떤 방식으로 해결해야 하는지를 한눈에 확인할 수 있도록 정리한 글입니다.

에러 메시지가 나타났다면, 아래 목록에서 해당 에러를 찾아 원인과 해결 방법을 확인하면 됩니다.

---

ModuleNotFoundError: No module named 'xxx'

에러 원인

• 필요한 모듈이 설치되어 있지 않은 경우입니다.
• 가상환경이 활성화되지 않은 상태에서 실행한 경우입니다.
• pip로 설치한 파이썬과 실제 실행 중인 파이썬 버전이 다른 경우입니다.

해결 방법

• 모듈이 설치되어 있는지 확인하고 설치합니다.

pip install 모듈이름

 

• 가상환경을 사용하는 경우, 가상환경이 활성화되어 있는지 확인합니다.
• 아래 명령어로 설치하면 버전 불일치 문제를 줄일 수 있습니다.

python -m pip install 모듈이름

 

---

IndentationError: unexpected indent

에러 원인

• 들여쓰기가 잘못된 경우입니다.
• 불필요한 들여쓰기가 포함된 경우입니다.
• 탭(Tab)과 스페이스(Space)를 혼용한 경우입니다.

해결 방법

• 들여쓰기는 스페이스 4칸으로 통일하는 것이 좋습니다.
• 코드 전체에서 탭 문자를 제거하고 스페이스로 변경합니다.
• 함수, 반복문, 조건문 내부의 들여쓰기 깊이를 다시 확인합니다.

---

SyntaxError: invalid syntax

에러 원인

• 문법적으로 잘못된 코드를 작성한 경우입니다.
• 콜론(:), 괄호, 따옴표가 누락된 경우가 많습니다.
• 예약어를 잘못 사용한 경우입니다.

해결 방법

• 에러 메시지에 표시된 줄 번호를 기준으로 문법을 확인합니다.
• 괄호와 따옴표가 모두 닫혀 있는지 확인합니다.
• if, for, while, def 문 뒤에 콜론이 있는지 확인합니다.

---

NameError: name 'xxx' is not defined

에러 원인

• 선언되지 않은 변수를 사용한 경우입니다.
• 변수 이름을 잘못 입력한 경우입니다.
• 함수 또는 변수가 정의되기 전에 사용된 경우입니다.

해결 방법

• 변수 또는 함수가 실제로 정의되어 있는지 확인합니다.
• 대소문자 오타 여부를 확인합니다.
• 코드 실행 순서를 점검합니다.

---

TypeError: unsupported operand type(s)

에러 원인

• 서로 다른 타입 간에 연산을 시도한 경우입니다.
• 함수에 잘못된 타입의 인자를 전달한 경우입니다.

해결 방법

• 연산 대상 변수들의 타입을 확인합니다.
• 필요한 경우 int(), str(), float() 등을 사용해 타입을 변환합니다.
• 함수 정의와 호출부의 인자 타입을 다시 확인합니다.

---

ValueError: invalid literal for int()

에러 원인

• 타입 변환은 가능하지만 값이 올바르지 않은 경우입니다.
• 숫자로 변환할 수 없는 문자열을 int()로 변환하려는 경우입니다.

해결 방법

• 변환 대상 데이터의 실제 값을 출력하여 확인합니다.
• 사용자 입력값의 경우 예외 처리를 추가하는 것이 좋습니다.

try:
    value = int(input())
except ValueError:
    print("숫자를 입력해야 합니다.")

---

IndexError: list index out of range

에러 원인

• 리스트의 범위를 벗어난 인덱스에 접근한 경우입니다.
• 반복문에서 인덱스 범위 설정이 잘못된 경우입니다.

해결 방법

• 리스트의 길이를 len()으로 확인합니다.
• 인덱스 접근 전에 범위 체크를 수행합니다.
• 반복문에서 range(len(list)) 사용 여부를 점검합니다.

---

AttributeError: 'xxx' object has no attribute 'yyy'

에러 원인

• 해당 객체에 존재하지 않는 속성이나 메서드를 호출한 경우입니다.
• 객체 타입을 잘못 이해하고 사용한 경우입니다.

해결 방법

• 객체의 실제 타입을 type()으로 확인합니다.
• 사용 가능한 속성과 메서드를 다시 확인합니다.
• 변수에 다른 타입의 값이 할당되지 않았는지 점검합니다.

---

UnicodeDecodeError: 'cp949' codec can't decode byte

에러 원인

• 파일 인코딩과 파이썬에서 읽으려는 인코딩이 다른 경우입니다.
• 윈도우 환경에서 자주 발생하는 에러입니다.

해결 방법

• 파일을 열 때 인코딩을 명시합니다.

open("file.txt", encoding="utf-8")

• 파일의 실제 인코딩을 확인한 후 맞는 인코딩을 지정합니다.

---

Python is not recognized as an internal or external command

에러 원인

• 파이썬이 설치되어 있지 않은 경우입니다.
• 환경 변수(Path)에 파이썬 경로가 등록되지 않은 경우입니다.

해결 방법

• 파이썬 설치 여부를 확인합니다.
• 설치 시 Add Python to PATH 옵션을 체크했는지 확인합니다.
• 환경 변수를 수동으로 설정합니다.

---

마무리

파이썬 에러 메시지는 문제 해결을 위한 힌트입니다.
에러 메시지를 두려워하기보다, 의미를 읽고 원인을 파악하는 습관이 중요합니다.

파이썬 에러가 발생했다면, 이 글을 기본 참고용 체크리스트로 활용하시기 바랍니다.

---