From: NewUserHa <32261870+NewUserHa@users.noreply.github.com>
Date: Thu, 5 Feb 2026 17:45:14 +0000 (+0800)
Subject: gh-142407: Clarify copy performance on Windows in shutil docs (GH-142408)
X-Git-Tag: v3.15.0a6~65
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d9a2e587fca4b4583dcea66d855b36b84320f98f;p=thirdparty%2FPython%2Fcpython.git

gh-142407: Clarify copy performance on Windows in shutil docs (GH-142408)
---

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 2c15fed8dd5e..ec3c8d600ad1 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -540,7 +540,9 @@ On Solaris :func:`os.sendfile` is used.
 
 On Windows :func:`shutil.copyfile` uses a bigger default buffer size (1 MiB
 instead of 64 KiB) and a :func:`memoryview`-based variant of
-:func:`shutil.copyfileobj` is used.
+:func:`shutil.copyfileobj` is used, which is still reads and writes in a loop.
+:func:`shutil.copy2` uses the native ``CopyFile2`` call on Windows, which is the most
+efficient method, supports copy-on-write, and preserves metadata.
 
 If the fast-copy operation fails and no data was written in the destination
 file then shutil will silently fallback on using less efficient