You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
rename() into an existing directory returns the directory for file:// paths #569
On current main (827574045b1fecad52f7af3cfeeab3ecd9a0d0e8), FilePath.rename() moves a file inside an existing directory and returns the directory rather than the moved file. A plain local UPath rejects the same operation with FileExistsError on my Windows machine.
Environment: Windows, CPython 3.14.3, universal_pathlib built from the commit above (0.3.10.post2+g827574045), fsspec 2026.7.0. I also reproduced the directory-return behavior with MemoryPath on Windows. The exact script above also reproduces on isolated Linux CPython 3.12.10 with the same UPath commit and fsspec 2026.7.0. The five original core/registry/relative/local/memory test modules pass there (1,002 passed, 5 skipped, 1 original xfail); this is not full Nox or cloud-backend validation.
FilePath uses UPath.rename(), which calls fs.mv() and returns the requested target. The local backend uses shutil.move(), so an existing directory is interpreted as a container. Renaming to a fresh filename works and returns the moved file.
I saw the warning about nonstandard recursive/maxdepth arguments and the recommendation to use move() or move_into(). Is moving a file into an existing directory also intentional for rename()? I expected it to reject that target, matching pathlib, rather than move the file and return its parent. If this behavior is kept for compatibility, documenting this distinction would help.
Found during AI-assisted source review and independently reproduced through the public API. No backend implementation was mocked or extracted for execution.
Thanks for the detailed report and reproducer @adenzhou1350! 🙏
This isn't intentional. UPath.rename() currently forwards to fsspec's mv(), which has cp/mv-like "move into an existing directory" semantics, and then returns the requested
target rather than the actual destination. This differs from pathlib.Path.rename() in
several cases:
src → dst
pathlib.Path (POSIX)
UPath file:// / memory:// / s3://
file → existing dir
IsADirectoryError
moved into dst, returns dst
dir → existing dir
replaces if empty, else OSError
moved into dst
dir → missing
✅
✅ file://, ❌ memory:// raised, ❌ s3:// silently did nothing
While investigating we found the last row: renaming directories raised on memory://
and was a silent no-op on s3:// unless the deprecated recursive=True keyword was passed.
That is fixed for the next release (0.3.11). Note that with fsspec>=2026.6.0 directory moves
on object stores currently hit an upstream regression (link to fsspec issue).
rename() already deviates from pathlib (the recursive/maxdepth keywords are
deprecated), and we want to align it fully with pathlib.Path.rename() in a future
release. Since changing the "move into an existing directory" behaviour could break code
that relies on it, we'll do that with a deprecation period rather than in a patch release.
In the meantime, if you want pathlib-like semantics today, use:
source.move(target): raises IsADirectoryError if target is an existing directory
source.move_into(target_dir): explicitly moves into an existing directory and returns
the actual new path
Activity
ap-- commentedon Nov 10, 2026
Thanks for the detailed report and reproducer @adenzhou1350! 🙏
This isn't intentional.
UPath.rename()currently forwards to fsspec'smv(), which hascp/mv-like "move into an existing directory" semantics, and then returns the requestedtarget rather than the actual destination. This differs from
pathlib.Path.rename()inseveral cases:
pathlib.Path(POSIX)UPathfile:// / memory:// / s3://IsADirectoryErrorOSErrorWhile investigating we found the last row: renaming directories raised on
memory://and was a silent no-op on
s3://unless the deprecatedrecursive=Truekeyword was passed.That is fixed for the next release (0.3.11). Note that with fsspec>=2026.6.0 directory moves
on object stores currently hit an upstream regression (link to fsspec issue).
rename()already deviates from pathlib (therecursive/maxdepthkeywords aredeprecated), and we want to align it fully with
pathlib.Path.rename()in a futurerelease. Since changing the "move into an existing directory" behaviour could break code
that relies on it, we'll do that with a deprecation period rather than in a patch release.
In the meantime, if you want pathlib-like semantics today, use:
source.move(target): raisesIsADirectoryErroriftargetis an existing directorysource.move_into(target_dir): explicitly moves into an existing directory and returnsthe actual new path
Keeping this issue open to track the alignment.
xref: #575