TrendPick100

파이썬 pathlib 모듈 완벽 가이드: OS 독립적 파일 경로 탐색과 디렉터리 제어

파이썬 pathlib 모듈을 활용하여 OS 독립적인 파일 경로 결합, 폴더 자동 생성(mkdir), glob 파일 탐색 및 FileNotFoundError 해결법을 알아봅니다.

본문 상단 광고 구역 (승인 후 자동 노출됩니다)

파이썬 스크립트로 파일 입출력이나 자동화 프로그램을 작성할 때 가장 빈번하게 발생하는 문제 중 하나가 바로 ‘파일 경로(Path)’ 오류입니다. 윈도우(Windows)는 역슬래시(\)를 경로 구분자로 사용하는 반면, 맥(macOS)과 리눅스(Linux)는 슬래시(/)를 사용하기 때문에 운영체제 간 스크립트 호환성이 깨지기 쉽습니다.

과거에는 os.path 모듈의 문자열 조합 방식을 주로 사용했으나, 파이썬 3.4부터 표준 라이브러리로 도입된 pathlib 모듈을 사용하면 객체 지향적인 방식으로 훨씬 직관적이고 안전하게 파일 시스템을 제어할 수 있습니다. pathlib의 기본 개념부터 실전 디렉터리 순회, 파일 생성 및 트러블슈팅까지 단계별로 정리합니다.

1. os.path와 pathlib의 차이점

기존의 os.path는 경로를 단순 문자열(String)로 취급하여 경로를 합치거나 분리할 때 코드가 길어지고 가독성이 떨어지는 단점이 있었습니다. 반면 pathlib은 경로를 하나의 독립된 ‘Path 객체’로 다룹니다.

  • 가독성 향상: 복잡한 함수 중첩 대신 직관적인 슬래시(/) 연산자를 사용하여 하위 디렉터리를 연결합니다.
  • 운영체제 독립성: 코드를 작성한 운영체제와 상관없이 실행되는 시스템의 파일 시스템 규격에 맞춰 경로 구분자를 자동 변환합니다.
  • 풍부한 내장 메서드: 파일 존재 여부 확인, 확장자 추출, 디렉터리 생성, 패턴 검색 등을 객체 메서드로 즉시 수행할 수 있습니다.

2. Path 객체 생성과 경로 결합

pathlib 모듈의 핵심 클래스는 Path입니다. 터미널이나 스크립트 상단에서 모듈을 임포트한 뒤 사용합니다.

1) 기본 경로 인스턴스 생성

현재 작업 디렉터리나 특정 파일의 경로를 정의하는 기본 코드입니다.

from pathlib import Path

# 현재 작업 디렉터리(Current Working Directory)
current_dir = Path.cwd()
print(f"현재 위치: {current_dir}")

# 사용자 홈 디렉터리
home_dir = Path.home()
print(f"홈 디렉터리: {home_dir}")

# 실행 중인 파이썬 스크립트의 절대 경로
script_path = Path(__file__).resolve()
print(f"스크립트 파일 경로: {script_path}")
print(f"스크립트가 위치한 폴더: {script_path.parent}")

2) 슬래시(/) 연산자를 통한 직관적인 경로 결합

os.path.join() 함수를 여러 번 중첩할 필요 없이, Path 객체 뒤에 슬래시(/) 기호를 붙여 하위 폴더나 파일명을 결합합니다.

from pathlib import Path

base_dir = Path.cwd()
# 'data' 폴더 안의 'reports' 폴더 안의 'result.csv' 경로 정의
target_file = base_dir / "data" / "reports" / "result.csv"

print(target_file)

3. 파일 및 경로 속성 분해

Path 객체는 파일 이름, 확장자, 부모 디렉터리 등을 별도의 파싱 작업 없이 속성값으로 제공합니다.

from pathlib import Path

p = Path("/home/user/project/data/summary_2026.xlsx")

# 1. 파일 전체 이름 (확장자 포함)
print(p.name)      # 출력: summary_2026.xlsx

# 2. 확장자를 제외한 순수 파일명
print(p.stem)      # 출력: summary_2026

# 3. 확장자
print(p.suffix)    # 출력: .xlsx

# 4. 부모 디렉터리 경로
print(p.parent)    # 출력: /home/user/project/data

# 5. 경로 존재 여부 및 파일/폴더 판별
print(p.exists())  # True 또는 False
print(p.is_file()) # 파일이면 True
print(p.is_dir())  # 디렉터리면 True

4. 디렉터리 자동 생성 및 파일 탐색 (glob)

실무 자동화에서 가장 자주 쓰이는 기능은 ‘결과물을 저장할 폴더 생성’과 ‘특정 확장자 파일 일괄 탐색’입니다.

1) 안전한 디렉터리 생성 (mkdir)

폴더가 이미 존재하거나 상위 디렉터리가 생성되어 있지 않을 때 발생하는 오류를 방지하기 위해 parents=True와 exist_ok=True 옵션을 필수로 사용합니다.

from pathlib import Path

output_dir = Path.cwd() / "output" / "monthly_reports"

# parents=True: 상위 폴더(output)가 없으면 함께 생성
# exist_ok=True: 폴더가 이미 존재해도 에러를 발생시키지 않음
output_dir.mkdir(parents=True, exist_ok=True)
print("디렉터리 생성 완료")

2) glob과 rglob을 활용한 파일 목록 순회

지정한 폴더 내의 특정 패턴을 가진 파일을 리스트로 추출합니다.

from pathlib import Path

target_dir = Path.cwd() / "data"

# 1. 현재 폴더 내 모든 CSV 파일 탐색
csv_files = list(target_dir.glob("*.csv"))
for file in csv_files:
    print(f"발견된 CSV 파일: {file.name}")

# 2. 하위 디렉터리까지 재귀적으로(Recursive) 모든 파이썬 파일 탐색
all_py_files = list(target_dir.rglob("*.py"))
for py_file in all_py_files:
    print(f"하위 파이썬 파일: {py_file}")

5. 자주 발생하는 오류 및 트러블슈팅

1) FileNotFoundError: 기준 경로 불일치

스크립트를 실행하는 터미널의 현재 위치(CWD)와 스크립트가 실제로 저장된 위치가 다를 때 상대 경로를 지정하면 파일을 찾지 못하는 문제가 발생합니다.

  • 원인: 터미널 실행 경로에 따라 Path.cwd()가 유동적으로 변하기 때문입니다.
  • 해결법: 항상 실행 중인 파일의 절대 위치를 기준으로 기준 경로를 고정합니다.
# 항상 이 스크립트가 위치한 폴더를 기준점으로 설정
BASE_DIR = Path(__file__).resolve().parent
DATA_PATH = BASE_DIR / "data" / "input.csv"

2) Windows 특유의 역슬래시 문자열 이스케이프 오류

윈도우 경로를 복사하여 Path(“C:\new_folder\test.txt”)처럼 전달할 경우 \n, \t가 줄바꿈이나 탭 문자로 잘못 인식되어 SyntaxError가 발생합니다.

  • 해결법: 문자열 앞에 r을 붙여 Raw String으로 처리하거나 슬래시(/)를 사용합니다.
# 올바른 예시 1: Raw String 사용
win_path = Path(r"C:\new_folder\test.txt")

# 올바른 예시 2: 슬래시 사용 (윈도우에서도 완벽 동작)
win_path = Path("C:/new_folder/test.txt")

6. 요약 및 마무리

파이썬의 pathlib은 크로스 플랫폼 호환성과 직관적인 코드 작성을 보장하는 파일 제어의 표준 도구입니다.

  • 경로 결합 시 문자열 연산 대신 Path 객체와 / 연산자를 사용합니다.
  • 폴더 생성 시 mkdir(parents=True, exist_ok=True) 조합을 습관화합니다.
  • 다수의 파일 탐색 시 glob()과 rglob()을 활용해 유지보수성을 극대화합니다.
본문 하단 광고 구역