Python Path.move 사용법

Python Path.move 사용법

pathlib.Path.move()는 파일이나 디렉터리 트리를 새 위치로 옮기고, 결과 경로를 다시 Path 객체로 돌려주는 표준 라이브러리 API다. 2026년 7월 17일 확인 기준 Python 3.14.6 공식 문서는 Path.move()와 Path.move_into()가 Python 3.14에서 추가됐다고 설명한다.

실무에서 볼 핵심은 세 가지다. 대상이 없으면 새 위치가 만들어질 수 있다는 점, 같은 파일시스템에서는 os.replace()로 처리되고 다른 파일시스템에서는 복사 후 삭제 방식으로 동작한다는 점, 이미 존재하는 디렉터리 안으로 넣고 싶을 때는 move_into()가 더 분명하다는 점이다.

Path.move는 언제 쓰면 될까?

다음 조건이면 Path.move()를 우선 검토할 만하다.

• 실행 환경이 Python 3.14 이상이다.
• 파일 하나와 디렉터리 트리를 같은 인터페이스로 옮기고 싶다.
• 코드베이스가 pathlib 중심이라 이동 결과를 다시 Path로 이어 쓰고 싶다.
• 교차 파일시스템 이동까지 포함한 동작 기준을 표준 문서 기준으로 명확히 알고 싶다.

반대로 Python 3.13 이하 호환이 필요하면 이 메서드를 기본 전제로 두면 안 된다. 이 경우에는 기존 방식 유지나 버전 분기가 필요하다.

기본 동작은 무엇일까?

Python 3.14.6 pathlib 문서 기준으로 Path.move(target)는 파일 또는 디렉터리 트리를 대상 경로로 옮기고, 그 결과를 가리키는 새 Path 객체를 반환한다.

항목	공식 문서 기준	실무 의미
지원 버전	Python 3.14 이상	하위 버전 호환 코드에는 바로 넣기 어렵다.
반환값	새 Path 객체	이동 직후 후속 연산을 이어 붙이기 쉽다.
대상이 없을 때	새 경로가 생성될 수 있음	파일명 변경과 위치 이동을 한 번에 표현할 수 있다.
기존 파일 충돌	원본과 대상이 모두 기존 파일이면 대상이 덮어써질 수 있음	실수로 기존 파일을 바꾸지 않도록 대상 경로 확인이 필요하다.
오류 조건	같은 파일/디렉터리를 가리키거나, 대상이 비어 있지 않은 디렉터리면 OSError	기존 디렉터리 병합 용도로 쓰는 API는 아니다.
같은 파일시스템	os.replace() 사용	일반적인 rename 계열 이동처럼 동작한다.
다른 파일시스템	메타데이터와 symlink를 보존하며 복사 후 삭제	파티션이나 마운트가 달라도 동작 기준을 예측하기 쉽다.

Path.move와 Path.move_into 차이는?

Path.move()는 최종 대상 경로를 직접 지정할 때 쓰고, Path.move_into()는 이미 존재하는 디렉터리 안으로 원본을 넣을 때 쓴다. Python 3.14.6 문서는 move_into(target_dir)의 대상이 existing directory여야 한다고 설명한다.

from pathlib import Path

src = Path("build/report.json")
archive_dir = Path("archive")

moved_file = src.move("archive/report-20260717.json")
moved_into_dir = src.move_into(archive_dir)

print(moved_file)
print(moved_into_dir)

파일명을 함께 바꾸거나 목적지 규칙이 복잡하면 move()가 더 자연스럽다. 반대로 "이 디렉터리 안으로 넣는다"는 의미를 드러내고 싶으면 move_into()가 읽기 쉽다.

교차 파일시스템 이동에서 왜 의미가 클까?

공식 문서는 원본과 대상이 같은 파일시스템이면 os.replace()로 이동하고, 그렇지 않으면 메타데이터와 symlink를 보존하며 복사한 뒤 원본을 삭제한다고 설명한다. 즉 단순 rename이 실패할 수 있는 경계에서도 Path.move()는 이동 의미를 한 API로 표현한다.

다만 이 설명은 동작 기준을 알려 주는 것이지, 모든 환경에서 비용이 같다는 뜻은 아니다. 다른 파일시스템으로 옮길 때는 실제 복사가 일어나므로 큰 디렉터리 트리에서는 시간과 I/O 비용을 따로 고려해야 한다.

어떤 경우에 OSError를 주의해야 할까?

Python 문서 기준으로 Path.move()는 두 경로가 같은 파일 또는 같은 디렉터리를 가리키면 OSError를 일으킨다. 또 대상이 비어 있지 않은 디렉터리여도 예외가 난다.

from pathlib import Path

src = Path("logs")

try:
    src.move("backup")
except OSError as exc:
    print(f"move failed: {exc}")

따라서 이 API는 "기존 디렉터리 트리에 합치기"보다 "지정한 새 위치로 옮기기"에 가깝다. 병합이나 부분 덮어쓰기가 필요하면 먼저 대상 상태를 점검하는 편이 안전하다.

기존 코드에서는 무엇과 비교하면 될까?

Python 3.14 변경 문서는 pathlib.Path에 재귀 복사·이동 메서드가 추가됐다고 설명한다. 따라서 이미 코드가 Path 객체 중심이라면 이동 로직도 같은 스타일로 정리하기 쉬워졌다.

실무 선택 기준은 단순하다. Python 3.14 이상이고 Path 기반 코드를 유지하고 싶으면 move()와 move_into()가 자연스럽다. 반대로 하위 버전 호환이 남아 있으면 기존 이동 API를 유지하는 편이 무난하다.

FAQ

Python 3.12나 3.13에서도 Path.move()를 쓸 수 있을까?

없다. Python 3.14 변경 문서는 move()와 move_into()를 3.14에서 추가된 기능으로 명시한다.

Path.move_into()가 대상 디렉터리를 자동으로 만들까?

공식 문서 표현은 existing directory다. 따라서 대상 디렉터리가 이미 있다고 보고 쓰는 편이 맞다.

다른 파일시스템으로 옮겨도 symlink와 메타데이터를 유지할까?

Python 3.14.6 pathlib 문서는 교차 파일시스템 이동에서 메타데이터와 symlink를 보존하며 복사한 뒤 삭제한다고 설명한다. 다만 실제 비용은 복사 작업이므로 큰 데이터셋에서는 성능 부담을 따로 봐야 한다.

정리

Path.move()와 Path.move_into()는 Python 3.14에서 추가된 파일시스템 이동 API다. 2026년 7월 17일 확인 기준 Python 3.14.6 공식 문서에 따르면, 이 메서드는 파일과 디렉터리 트리를 옮기고 결과를 다시 Path 객체로 돌려준다.

판단 기준은 네 가지면 충분하다. Python 3.14 이상인지, 대상 디렉터리가 이미 있는지, 기존 비어 있지 않은 디렉터리와 병합할 의도가 있는지, 교차 파일시스템 복사 비용을 감수할 수 있는지다. 이 조건이 맞으면 pathlib 코드에서 꽤 읽기 좋은 기본 선택지가 된다.

참고 자료

• Python 3.14.6 공식 문서: pathlib
• Python 3.14 공식 변경 문서