Activity

1. LazyDodo

   added

   type-bugAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error

   on May 1, 2023
2. arhadthedev

   added

   OS-windows

   stdlibStandard Library Python modules in the Lib/ directoryStandard Library Python modules in the Lib/ directory

   on May 1, 2023
3. eryksun commented on May 1, 2023

   

   eryksun

   on May 1, 2023

   Contributor

   More actions

   A junction is like a Unix bind mount point. So, for comparison, let's take a look at the behavior of shutil.copytree() with a bind mount point on Linux.

   #!/usr/bin/bash
   # repro.sh
   # Create some important files
   mkdir source
   echo 'print("world")' > source/hello.py
   
   # Create a project with a bind mount to the source folder
   mkdir -p project1/test
   mount --bind source project1/test
   
   # Create a second project with a bind mount to the source folder
   mkdir -p project2/test
   mount --bind source project2/test
   
   ls -1shR > before.txt
   
   # Case 1: Copy project1 to a whole new folder.
   # This will copy the files, but will lose the mount point even though we asked
   # to copy symlinks. After the copy project3/test/hello.py and source/hello.py
   # will be individual files; changes to one do not affect the other.
   python -c 'import shutil; shutil.copytree("project1", "project3", dirs_exist_ok=True, symlinks=True)'
   ls -1shR > case1.txt
   
   # Case 2: Copy 2 folders with identical bind mounts already in place on top of
   # each other. This fails because the _samefile(src, dst) call in
   # shutil.copyfile() is true for "hello.py".
   python -c 'import shutil; shutil.copytree("project1", "project2", dirs_exist_ok=True, symlinks=True)'
   ls -1shR > case2.txt
   
   umount project1/test
   umount project2/test

   As expected for case 1, shutil.copytree() copies a new "hello.py" file, as shown by the differing inode numbers.

   # stat -c %i source/hello.py
   22807104
   # stat -c %i project3/test/hello.py
   22807167
   

   For case 2, on the other hand, trying to copy the "project1" bind mount onto the "project2" bind mount fails because "hello.py" is the same file.

   shutil.Error: ['<', 'D', 'i', 'r', 'E', 'n', 't', 'r', 'y', ' ', "'", 'h', 'e', 'l', 'l', 'o', '.', 'p', 'y', "'", '>', ' ', 'a', 'n', 'd', ' ', "'", 'p', 'r', 'o', 'j', 'e', 'c', 't', '2', '/', 't', 'e', 's', 't', '/', 'h', 'e', 'l', 'l', 'o', '.', 'p', 'y', "'", ' ', 'a', 'r', 'e', ' ', 't', 'h', 'e', ' ', 's', 'a', 'm', 'e', ' ', 'f', 'i', 'l', 'e']
   

   Aside from the bad formatting of the error message, the interesting part is that it's comparing a source path that's an os.DirEntry instance with a target path that's a string. Let's check the implementation of shutil._samefile():

   cpython/Lib/shutil.py

   Lines 204 to 216 in d448fcb

   	def _samefile(src, dst):
   	# Macintosh, Unix.
   	if isinstance(src, os.DirEntry) and hasattr(os.path, 'samestat'):
   	try:
   	return os.path.samestat(src.stat(), os.stat(dst))
   	except OSError:
   	return False
   	if hasattr(os.path, 'samefile'):
   	try:
   	return os.path.samefile(src, dst)
   	except OSError:
   	return False

   On Windows, the values of st_dev and st_ino from the result of os.DirEntry.stat() are both 0¹, unless it's a symlink. On the other hand, for os.stat() the value of st_dev is the volume serial number, and the value of st_ino is the file ID². Thus even though it's the same file, os.path.samestat(src.stat(), os.stat(dst)) returns false.

   On Windows, shutil._samefile() should prefer os.path.samefile(). This is still a flawed comparison because it relies on the st_dev and st_ino stat values, which may both be 0 on Windows (e.g. a WebDAV filesystem), but at least there's an open issue to implement a more rigorous ntpath.samefile() that compares the final NT path name when the st_dev or st_ino value is unreliable.

   Footnotes

   1. It's possible to redesign os.scandir() on Windows to get st_dev and st_ino cheaply in the os.DirEntry.stat() result. Instead of using FindFirstFileW() and FindNextFileW(), directly open the directory and call GetVolumeInformationByHandleW() to get the volume serial number, which only has to be called once. For the directory listing itself, use the same handle to call GetFileInformationByHandleEx() to get the FileIdBothDirectoryInfo, in batches with a buffer size of 64 KiB, which provides the basic stat info and file ID for each entry. ↩

   2. The volume serial number and file ID may be 0 if the filesystem doesn't support them. However, they're commonly supported, except by some filesystem redirectors such as WebDAV. ↩
4. eryksun commented on May 1, 2023

   

   eryksun

   on May 1, 2023

   Contributor

   More actions

   Note that if the Windows batch script is changed to use mklink /D to create directory symbolic links, and the shutil.copytree() call is changed to use symlinks=False, then in this case "source\hello.py" also gets truncated. It's due to the same design flaw in shutil._samefile().
5. gvking

   added a commit that references this issue on Apr 1, 2026

   pythongh-104046: Fix Windows junction handling in shutil.copytree()

   ...

   74fbeec
6. sankalpsthakur

   added 2 commits that reference this issue on Oct 7, 2026

   Merge branch 'main' into fix/pythongh-104046-direntry-samefile

   c15b99f

   Merge branch 'main' into fix/pythongh-104046-direntry-samefile

   a2ae6d3