Python Path.copy 사용법

Python Path.copy 사용법

pathlib.Path.copy()는 파일이나 디렉터리 트리를 복사한 뒤 새 경로를 다시 Path 객체로 돌려주는 표준 라이브러리 API다. 2026년 6월 7일 확인한 Python 3.14.5 공식 문서 기준으로 Path.copy()와 Path.copy_into()는 Python 3.14에서 추가됐다.

실무에서 볼 핵심은 세 가지다. Python 3.14 이상에서만 쓸 수 있다는 점, 심볼릭 링크를 따라갈지 여부를 follow_symlinks로 고른다는 점, 메타데이터 보존 범위를 preserve_metadata로 조절한다는 점이다. 이미 코드가 pathlib 중심이면 shutil.copy2()와 copytree()보다 읽기 쉬운 경우가 많다.

Path.copy는 언제 쓰면 될까?

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

• 실행 환경이 Python 3.14 이상이다.
• 입력과 출력 경로를 모두 Path 객체로 다루고 있다.
• 파일 하나와 디렉터리 트리를 같은 인터페이스로 복사하고 싶다.
• 복사 후 결과 경로를 다시 Path 연산으로 바로 이어 쓰고 싶다.

반대로 Python 3.13 이하도 지원해야 하면 이 메서드를 기본 전제로 두면 안 된다. 그 경우에는 shutil.copy2()와 shutil.copytree()를 유지하거나 버전 분기가 필요하다.

기본 동작은 무엇일까?

Python 3.14 pathlib 문서는 Path.copy(target, *, follow_symlinks=True, preserve_metadata=False)가 파일 또는 디렉터리 트리를 대상 경로로 복사하고, 복사된 위치를 가리키는 새 Path 객체를 반환한다고 설명한다.

항목	공식 문서 기준	실무 의미
지원 버전	Python 3.14 이상	하위 버전 호환이 필요하면 대체 API가 필요하다.
반환값	새 Path 객체	복사 직후 후속 처리 연결이 자연스럽다.
파일 대상 충돌	원본이 파일이고 대상도 기존 파일이면 덮어쓴다.	실수로 기존 파일을 바꾸지 않도록 대상 경로를 확인해야 한다.
심볼릭 링크 기본값	follow_symlinks=True	기본적으로 링크 자체보다 링크가 가리키는 내용을 복사한다.
메타데이터 기본값	preserve_metadata=False	기본값만으로는 데이터와 디렉터리 구조 위주 복사라고 보는 편이 안전하다.

Path.copy와 Path.copy_into 차이는?

Path.copy()는 대상 전체 경로를 직접 지정할 때 쓰고, Path.copy_into()는 이미 존재하는 디렉터리 안으로 복사할 때 쓴다. Python 3.14.5 문서는 copy_into(target_dir)의 대상은 existing directory여야 하며, 나머지 인수는 Path.copy()와 동일하게 처리된다고 설명한다.

from pathlib import Path

src = Path("data/report.csv")
backup_dir = Path("backup")

copied_file = src.copy("backup/report-20260607.csv")
copied_into_dir = src.copy_into(backup_dir)

print(copied_file)
print(copied_into_dir)

대상 디렉터리가 이미 정해져 있다면 copy_into()가 의도를 더 잘 드러낸다. 반면 파일명을 바꾸거나 다른 경로 규칙으로 보낼 때는 copy()가 더 직관적이다.

심볼릭 링크는 어떻게 처리될까?

공식 문서 기준 기본값은 follow_symlinks=True다. 즉 원본이 심볼릭 링크라면 링크 자체를 복사하는 대신, 그 링크가 가리키는 대상을 복사한다. 링크 자체를 다시 만들고 싶으면 follow_symlinks=False를 명시해야 한다.

from pathlib import Path

src = Path("current.log")

# 링크 대상 내용을 복사
copied_target = src.copy("archive/log-copy.txt")

# 심볼릭 링크 자체를 다시 생성
copied_link = src.copy("archive/current.log", follow_symlinks=False)

배포 스크립트나 백업 작업에서 이 차이는 중요하다. 실제 파일 내용을 보존해야 하는지, 링크 구조 자체를 유지해야 하는지 먼저 정해 두는 편이 안전하다.

preserve_metadata는 어디까지 믿어야 할까?

Python 3.14.5 문서는 preserve_metadata=False일 때 디렉터리 구조와 파일 데이터만 보장된다고 설명한다. True로 바꾸면 권한, 플래그, 접근 시각, 수정 시각, 확장 속성을 지원되는 환경에서 복사하려고 시도한다. 다만 파일 복사 시 Windows에서는 메타데이터가 항상 보존되므로 이 인수는 효과가 없다고 명시한다.

즉 권한 비트나 타임스탬프가 의미 있는 운영 스크립트라면 기본값을 그대로 두기보다 preserve_metadata=True를 검토해야 한다. 반대로 단순 산출물 백업이나 캐시 복사처럼 내용만 중요하면 기본값도 충분할 수 있다.

shutil.copy2, copytree와는 어떻게 고르면 될까?

Path.copy()는 새 기능이지만 기존 API를 완전히 대체해야 한다는 뜻은 아니다. Python 공식 문서 기준으로 shutil.copy2()는 파일 메타데이터를 함께 복사하고, copytree()는 디렉터리 트리를 재귀 복사한다. 따라서 선택 기준은 주로 코드 스타일과 지원 버전에 달려 있다.

• Python 3.14 이상이고 Path 중심 코드라면 Path.copy()가 더 자연스럽다.
• Python 3.13 이하 호환이 필요하면 shutil.copy2(), copytree()가 안전하다.
• 대상 디렉터리가 이미 있고 그 안으로 넣는 의미를 드러내고 싶으면 Path.copy_into()가 읽기 쉽다.

Python 문서는 또 이 메서드가 운영체제와 파일시스템이 지원하면 copy-on-write 방식의 lightweight copy를 수행할 수 있다고 설명한다. 다만 이는 지원 환경에서의 최적화이므로, 모든 플랫폼에서 같은 성능 특성을 기대하는 식으로 일반화하면 안 된다.

자주 헷갈리는 질문

1. Path.copy는 기존 대상 파일을 덮어쓸 수 있을까?

그럴 수 있다. 공식 문서는 원본이 파일이고 대상이 기존 파일이면 그 파일이 대체된다고 설명한다.

2. Path.copy_into는 대상 디렉터리를 자동 생성할까?

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

3. Python 3.12나 3.13에서도 같은 메서드가 있을까?

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

FAQ

Q. 새 프로젝트라면 shutil 대신 Path.copy로 통일해도 될까?

실행 환경을 Python 3.14 이상으로 고정할 수 있고, 코드베이스가 pathlib 중심이라면 충분히 검토할 만하다. 다만 하위 버전 호환 요구가 남아 있으면 아직은 shutil 계열이 더 무난하다.

Q. 메타데이터 보존이 중요하면 어떤 값을 먼저 볼까?

preserve_metadata=True 여부를 먼저 확인하는 편이 좋다. 기본값은 데이터와 구조 보장 쪽에 가깝고, 자세한 보존 범위는 플랫폼 지원 여부에 따라 달라질 수 있다.

Q. 링크 파일을 링크 그대로 백업하려면?

follow_symlinks=False를 사용해야 한다. 기본값은 링크 대상을 복사하는 쪽이다.

정리

Path.copy()와 Path.copy_into()는 Python 3.14에서 추가된 파일시스템 복사 API다. 2026년 6월 7일 확인한 Python 3.14.5 공식 문서 기준으로, 이 메서드는 파일과 디렉터리 트리를 복사하고 결과를 다시 Path 객체로 돌려준다.

선택 기준은 단순하다. Python 3.14 이상인지, 심볼릭 링크를 따라갈지, 메타데이터 보존이 중요한지 세 가지를 먼저 보면 된다. 그 조건이 맞으면 pathlib 기반 코드에서는 꽤 깔끔한 기본 선택지가 된다.

참고 자료

• Python 3.14.5 pathlib 문서
• What’s New in Python 3.14
• Python 3.14.5 shutil 문서