Skip to content

Conversation

@xiatianxuan
Copy link

@xiatianxuan xiatianxuan commented Jan 31, 2026

The current documentation for shutil implies that all copy functions benefit from fast kernel-space copying on Windows via the CopyFile2 API. However, shutil.copyfile() is an exception — it still uses a userspace read/write loop.

This PR clarifies that:

  • shutil.copy(), copy2(), copytree(), and move() use CopyFile2 (when available)
  • shutil.copyfile() does not, and remains a buffered userspace copy
  • Provides practical guidance: prefer copy2() over copyfile() for better performance on Windows when metadata preservation is acceptable

The change has been verified by:

  • Building the docs locally with make html (0 warnings)
  • Confirming the rendered HTML displays the updated text correctly

Related to GH-142407.


📚 Documentation preview 📚: https://cpython-previews--144354.org.readthedocs.build/

@python-cla-bot
Copy link

python-cla-bot bot commented Jan 31, 2026

All commit authors signed the Contributor License Agreement.

CLA signed

@bedevere-app bedevere-app bot added docs Documentation in the Doc dir skip news awaiting review labels Jan 31, 2026
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Jan 31, 2026
@xiatianxuan xiatianxuan changed the title Doc: Clarify that shutil.copyfile() does not use CopyFile2 on Windows GH-142407: Doc: Clarify shutil.copyfile() does not use CopyFile2 on Windows Jan 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

1 participant