Skip to content

Commit 9f3e372

Browse files
committed
gh-125676:clarify shutil.copy2/copy behavior and move fallback
1 parent 8665769 commit 9f3e372

File tree

1 file changed

+7
-3
lines changed

1 file changed

+7
-3
lines changed

Doc/library/shutil.rst

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -204,9 +204,13 @@ Directory and files operations
204204
*src* symbolic link to the newly created *dst* symbolic link.
205205
However, this functionality is not available on all platforms.
206206
On platforms where some or all of this functionality is
207-
unavailable, :func:`copy2` will preserve all the metadata
208-
it can; :func:`copy2` never raises an exception because it
209-
cannot preserve file metadata.
207+
unavailable, :func:`copy2` will preserve as much metadata as it
208+
can. However, individual metadata-copy operations (for example
209+
changing ownership or setting certain flags) may fail on some
210+
platforms or when the current process lacks privileges; such
211+
failures can raise exceptions. If you need to avoid metadata-related
212+
errors, use :func:`~shutil.copy`, which copies file data and the
213+
permission bits but does not attempt to preserve other metadata.
210214

211215
:func:`copy2` uses :func:`copystat` to copy the file metadata.
212216
Please see :func:`copystat` for more information

0 commit comments

Comments
 (0)