12. Python FileNotFoundError(파일 또는 경로 없음) 완벽 가이드

이 글에서는 Python에서 파일 입출력 작업 중 가장 흔히 마주치는 FileNotFoundError—파일이나 경로를 찾을 수 없어 발생하는 예외의 정의와 동작 원리, 실제 사례를 통해 이해하고, 예외 발생 원인 분석과 함께 현장에서 바로 적용 가능한 해결 방법 및 디버깅 팁을 단계별로 설명합니다. 마지막에는 다음 챕터인 UnicodeError: 인코딩·디코딩 오류 예고를 포함해, 파일 입출력 전반에 대한 통합적인 학습 로드맵을 제시합니다.

1. FileNotFoundError란?

FileNotFoundError는 Python의 내장 예외 중 하나로, 파일을 열거나(os.open), 읽거나(open), 경로 관련 작업(os.path 등)을 수행할 때 지정한 경로에 파일이나 디렉터리가 존재하지 않으면 발생합니다. Python 3부터는 IOError의 하위 클래스가 아닌 독립적인 예외로 구분되며, 파일 시스템과 상호작용하는 모든 함수에서 공통적으로 사용할 수 있습니다.

예를 들어, open("data/input.txt", "r") 호출 시 해당 경로에 파일이 없으면 즉시 FileNotFoundError가 발생하며, 메시지에는 “[Errno 2] No such file or directory: 'data/input.txt'” 형태로 오류 코드와 경로 정보를 제공합니다. 이는 런타임 단계에서 감지되며, 사전 경로 검증 없이 파일 입출력 함수에 의존할 때 프로그램이 중단되는 대표적인 사례입니다.

2. 주요 발생 원인

• 잘못된 파일 경로: 절대/상대 경로가 코드 실행 위치와 일치하지 않을 때
• 파일명 오타: 대소문자 구분이 있는 운영체제에서 철자나 확장자(.txt/.csv 등)가 다를 때
• 디렉터리 미생성: 상위 디렉터리가 없는데 하위 파일을 열거나 쓰기 모드로 접근할 때
• 작업 디렉터리 변경: 스크립트가 실행되는 현재 작업 디렉터리(CWD)가 예상과 달라 상대경로가 꼬일 때
• 파일 이동 또는 삭제: 외부 프로세스나 사용자가 실행 중에 파일을 이동·삭제한 경우
• 권한 문제: 경로는 존재하지만 접근 권한이 없어 시스템상 “찾을 수 없음”으로 처리될 때

위 원인 중 하나라도 발생하면 파일 시스템 호출이 실패하며 FileNotFoundError가 발생합니다. 특히 대규모 프로젝트에서는 환경별 경로 설정이 달라지기 쉽기 때문에, 배포 및 운영 환경을 아우르는 경로 관리 전략이 필요합니다.

3. 실습 예제

아래 예제에서는 가장 기본적인 open() 호출에서 FileNotFoundError가 발생하는 상황을 재현합니다.

# 예제 1: 존재하지 않는 파일 열기
try:
    f = open("logs/app.log", "r")
    data = f.read()
    f.close()
except FileNotFoundError as e:
    print("오류 발생:", e)

# 예제 2: 디렉터리 생성 없이 쓰기 모드 호출
try:
    f = open("output/results/data.csv", "w")
    f.write("id,value\n1,100")
    f.close()
except FileNotFoundError as e:
    print("오류 발생:", e)

첫 번째 예제는 logs 디렉터리 또는 app.log 파일이 없어서, 두 번째 예제는 output/results 디렉터리가 없기 때문에 FileNotFoundError가 발생합니다. 각 예제에서 except 블록으로 전달되는 예외 객체의 메시지를 통해 정확한 경로 정보를 확인할 수 있습니다.

4. 실행 결과 및 설명

오류 발생: [Errno 2] No such file or directory: 'logs/app.log'
오류 발생: [Errno 2] No such file or directory: 'output/results/data.csv'

출력 메시지는 OS 오류 번호와 함께 경로를 명시하므로, 오류 로깅 시 사용자에게 어떤 경로에서 문제가 발생했는지 직관적으로 전달할 수 있습니다. 특히 운영 환경에서는 로그 분석 시스템으로 수집해 반복적으로 발생하는 경로 이슈를 추적할 때 유용합니다.

5. 해결 방법 & 디버깅 팁

1. 경로 사전 검증

   import os
   if os.path.exists(path):
       with open(path, "r") as f:
           ...
   else:
       print("경로가 존재하지 않습니다:", path)
   

   파일 호출 전 os.path.exists()로 존재 여부를 확인해 안전하게 분기 처리합니다.
2. 디렉터리 자동 생성

   import os
   os.makedirs(os.path.dirname(path), exist_ok=True)
   with open(path, "w") as f:
       ...
   

   쓰기 모드로 파일을 생성할 때 필요한 상위 디렉터리를 미리 생성해 줍니다.
3. 절대경로 사용

   import os
   BASE_DIR = os.path.dirname(os.path.abspath(__file__))
   path = os.path.join(BASE_DIR, "data", "input.txt")
   

   프로젝트 루트 기준 절대경로를 사용해 작업 디렉터리 변경에 영향을 받지 않도록 합니다.
4. 환경별 설정 관리 - 개발·테스트·운영 환경별로 설정 파일(config.json, .env 등)에 경로를 분리 관리해 코드 수정 없이 환경 전환이 가능하도록 합니다.
5. 로깅과 알림 통합 - logging 모듈로 FileNotFoundError를 캡처해 상세 정보를 기록하고, 필요시 이메일·Slack 알림을 보내 즉각 대응할 수 있도록 구성합니다.

6. 정리 및 다음 단계

이번 챕터에서는 FileNotFoundError의 정의와 발생 원인, 실습 예제, 실행 결과 및 현장에서 적용 가능한 해결 방법을 다루었습니다. 경로 검증, 디렉터리 자동 생성, 절대경로 사용과 환경별 설정 관리를 통해 파일 찾기 문제를 사전에 예방하고, 예외 처리 로직을 통해 안정적인 파일 입출력 시스템을 구축할 수 있습니다. 다음 챕터에서는 UnicodeError: 인코딩·디코딩 오류 문제를 심층 분석할 예정이니 많은 기대 부탁드립니다!