From d9a2e587fca4b4583dcea66d855b36b84320f98f Mon Sep 17 00:00:00 2001
From: NewUserHa <32261870+NewUserHa@users.noreply.github.com>
Date: Fri, 6 Feb 2026 01:45:14 +0800
Subject: [PATCH] gh-142407: Clarify copy performance on Windows in shutil docs
 (GH-142408)

---
 Doc/library/shutil.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 2c15fed8dd5..ec3c8d600ad 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