Python Path.walk 사용법

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Python Path.walk 사용법

pathlib.Path.walk()는 디렉터리 트리를 순회할 때 os.walk() 대신 검토할 수 있는 표준 라이브러리 API다. Python 공식 문서 기준으로 이 메서드는 Python 3.12에서 추가됐고, 현재 Python 3.14 문서에도 같은 동작 모델이 정리돼 있다.

핵심은 세 가지다. dirpath는 문자열이 아니라 Path 객체로 전달되고, top_down=True일 때는 dirnames를 직접 수정해 하위 탐색을 줄일 수 있으며, 기본값에서는 심볼릭 링크를 따라가지 않는다. 이 글은 Python 공식 문서와 변경 기록을 바탕으로 실무에서 바로 판단할 기준만 정리한다.

Path.walk는 언제 쓰면 될까?

다음 조건이면 Path.walk()를 기본 후보로 두기 좋다.

• 실행 환경이 Python 3.12 이상이다.
• 이미 코드베이스가 pathlib.Path 중심으로 작성돼 있다.
• 순회 결과를 다시 Path 연산으로 이어 붙이고 싶다.
• 특정 하위 디렉터리를 제외하는 prune 처리가 필요하다.

반대로 Python 3.11 이하 호환이 필요하면 이 API를 전제로 설계하면 안 된다. 그 경우에는 os.walk()를 유지하거나 버전 조건 분기가 필요하다.

반환값은 어떻게 생겼을까?

Python 3.14 pathlib 문서는 Path.walk(top_down=True, on_error=None, follow_symlinks=False)가 각 디렉터리마다 (dirpath, dirnames, filenames) 3튜플을 만든다고 설명한다. 여기서 dirpath는 현재 디렉터리를 가리키는 Path 객체이고, dirnames와 filenames는 이름 문자열 목록이다.

from pathlib import Path

root = Path("src")

for dirpath, dirnames, filenames in root.walk():
    print(dirpath)
    print(dirnames)
    print(filenames)

파일의 전체 경로가 필요하면 dirpath / name처럼 다시 조합하면 된다. 이 점이 문자열 경로를 돌려주는 기존 습관보다 읽기 쉬운 경우가 많다.

os.walk와 가장 큰 차이는 무엇일까?

가장 눈에 띄는 차이는 심볼릭 링크 분류 방식이다. Python 3.12 문서는 os.walk()가 디렉터리 여부를 분류할 때 심볼릭 링크를 따라가지만, Path.walk()는 follow_symlinks=False일 때 모든 심볼릭 링크를 filenames 쪽으로 분류한다고 설명한다.

즉 기존 os.walk() 코드를 그대로 옮기면, 링크 디렉터리가 dirnames에서 보이지 않아 탐색 결과가 달라질 수 있다. 디렉터리 링크까지 실제로 내려가야 하는 작업이라면 follow_symlinks=True를 의식적으로 지정해야 한다.

하위 디렉터리를 제외하고 싶다면?

top_down=True일 때는 호출자가 dirnames 목록을 직접 수정할 수 있다. Python 문서는 이 방식으로 탐색 가지치기(prune), 방문 순서 제어, 순회 중 생성한 디렉터리 반영이 가능하다고 설명한다.

from pathlib import Path

root = Path(".")

for dirpath, dirnames, filenames in root.walk():
    dirnames[:] = [name for name in dirnames if name not in {".git", "__pycache__", "node_modules"}]
    for filename in filenames:
        print(dirpath / filename)

이 패턴은 대용량 저장소를 훑을 때 특히 유용하다. 다만 top_down=False에서는 이미 하위 디렉터리가 생성된 뒤라서 dirnames 수정이 동작에 영향을 주지 않는다.

에러 처리는 어떻게 보는 편이 좋을까?

기본값에서는 os.scandir()가 내는 오류가 무시된다. Python 공식 문서는 on_error에 호출 가능 객체를 넘기면 OSError를 받아 계속 진행하거나 다시 예외를 던져 중단할 수 있다고 설명한다.

from pathlib import Path

def handle_error(exc: OSError) -> None:
    print(f"scan failed: {exc.filename}: {exc.strerror}")

for dirpath, dirnames, filenames in Path("/var").walk(on_error=handle_error):
    pass

운영 환경에서 권한 문제나 일시적 파일시스템 오류를 추적해야 한다면 기본 무시 동작에만 기대지 않는 편이 낫다. 반대로 best-effort 스캔이면 기본값이 더 단순하다.

 

 

follow_symlinks는 언제 켜야 할까?

심볼릭 링크가 가리키는 디렉터리까지 실제로 순회 대상에 포함해야 할 때만 켜는 편이 안전하다. Python 3.14 문서는 follow_symlinks=True가 부모 디렉터리를 다시 가리키는 링크를 만나면 무한 재귀로 이어질 수 있고, Path.walk()는 이미 방문한 디렉터리를 추적하지 않는다고 경고한다.

따라서 백업, 코드 인덱싱, 로그 수집처럼 디렉터리 트리 전체를 자동 순회하는 작업에서는 기본값 False가 더 보수적이다. 링크까지 내려가야 한다면 방문 집합 관리나 최대 깊이 같은 별도 안전장치를 같이 두는 편이 낫다.

실무에서는 어떤 패턴이 무난할까?

대부분의 프로젝트에서는 아래 기준으로 판단하면 된다.

• Python 3.12 이상이고 pathlib를 이미 쓰고 있다면 Path.walk()를 우선 검토한다.
• 숨기고 싶은 디렉터리가 있으면 top_down=True와 dirnames 수정 패턴을 같이 쓴다.
• 권한 오류를 로그로 남겨야 하면 on_error를 설정한다.
• 심볼릭 링크 순회는 필요한 경우에만 follow_symlinks=True로 연다.

즉 이 API의 장점은 단순히 os.walk()의 대체제가 아니라, Path 객체 기반 코드와 더 자연스럽게 이어진다는 데 있다. 반면 링크 처리와 버전 호환성은 반드시 같이 확인해야 한다.

FAQ

Python 3.11 이하에서도 Path.walk를 쓸 수 있을까?

표준 라이브러리 Path.walk()는 Python 3.12에서 추가됐다. 따라서 Python 3.11 이하에서는 같은 이름의 메서드를 전제로 작성할 수 없다.

dirnames를 수정하면 정말 하위 탐색이 줄어들까?

그렇다. Python 공식 문서는 top_down=True일 때 호출자가 dirnames를 제자리에서 수정하면 남아 있는 디렉터리만 재귀 대상으로 사용한다고 설명한다.

심볼릭 링크를 따라가면 무엇을 조심해야 할까?

부모를 다시 가리키는 링크가 있으면 무한 재귀가 생길 수 있다. Python 공식 문서는 Path.walk()가 이미 방문한 디렉터리를 기억하지 않는다고 명시한다.

참고 자료

• Python 3.14 pathlib 문서
• Python 3.12 pathlib 문서
• Python 3.12 changelog