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
UNC paths are broken when parsing file:// URIs (authority ignored, round-trip fails) #557
UNC paths are broken when parsing file:// URIs (authority ignored, round-trip fails)
Description
First of all, thank you for maintaining this great library — it’s very useful and appreciated.
I’ve encountered an issue when handling UNC paths via file:// URIs, where the authority component is ignored and the path is incorrectly interpreted as a local path.
I can reproduce this on Windows on current main, and it is worse than a failed round-trip: UPath("file://server/share/f") resolves to <cwd>/server/share/f. fsspec's LocalFileSystem treats file://host/... as relative on purpose (there is a test for it in test_strip_protocol_windows_remote_shares), so I think the fix belongs in upath's file-URI handling. Would you accept a PR that maps a non-empty, non-localhost authority to //host/... on Windows? Happy to take it if so.
Hi @t-onoz, you're right, and thanks for pointing it out 🙏
WindowsUPath.as_uri() behaves exactly like pathlib.Path.as_uri() and returns the
RFC 8089 form file://server/share/file, and we'll keep it that way.
The actual problem is that UPath("file://...") doesn't parse RFC 8089 URIs. It parses fsspec urlpaths, and fsspec's LocalFileSystem strips file:// as a plain prefix and
treats the rest literally as a path. So the authority server becomes the first segment of
a relative path that gets resolved against the current working directory. The same mismatch
also affects percent-encoded characters, e.g. a space becomes a literal %20 in the path.
fsspec's own test-suite pins this behaviour:
On Python >= 3.13 this already works today. On older Python versions our from_uri()
backport was broken, which is fixed in the next release (0.3.11). In 0.4.0, UPath.from_uri(uri) will also follow pathlib.Path.from_uri() for file: URIs (it
currently behaves like UPath(uri)). We also documented the difference between the two
string forms.
Longer term it would be nice if fsspec interpreted the authority of file:// URIs; I'll
raise that upstream.
Closing via #574, and closing #564 in favour of it.
Thanks again!
Activity
itzzdev09 commentedon Sep 16, 2026
I can reproduce this on Windows on current
main, and it is worse than a failed round-trip:UPath("file://server/share/f")resolves to<cwd>/server/share/f. fsspec'sLocalFileSystemtreatsfile://host/...as relative on purpose (there is a test for it intest_strip_protocol_windows_remote_shares), so I think the fix belongs in upath's file-URI handling. Would you accept a PR that maps a non-empty, non-localhost authority to//host/...on Windows? Happy to take it if so.ap-- commentedon Sep 17, 2026
Hi both,
This is a bug yes.
as_uri()should returnfile:////server/share/filein this case:PR is welcome 🙏
Cheers,☺️
Andreas
t-onoz commentedon Oct 3, 2026
@ap--
In stdlib
pathlib,as_uri()returnsfile://server/share/file. Isfile:////server/share/filereally correct?ap-- commentedon Nov 10, 2026
Hi @t-onoz, you're right, and thanks for pointing it out 🙏
WindowsUPath.as_uri()behaves exactly likepathlib.Path.as_uri()and returns theRFC 8089 form
file://server/share/file, and we'll keep it that way.The actual problem is that
UPath("file://...")doesn't parse RFC 8089 URIs. It parsesfsspec urlpaths, and fsspec's
LocalFileSystemstripsfile://as a plain prefix andtreats the rest literally as a path. So the authority
serverbecomes the first segment ofa relative path that gets resolved against the current working directory. The same mismatch
also affects percent-encoded characters, e.g. a space becomes a literal
%20in the path.fsspec's own test-suite pins this behaviour:
So there are two kinds of
file:strings:PosixUPath/WindowsUPathFilePath(fsspec based)p.as_uri(): RFC 8089 file URI, same as pathlibstr(p): fsspec urlpathUPath.from_uri(uri)/WindowsUPath.from_uri(uri)UPath(urlpath)The fix for your use case is to use
from_uri(), the inverse ofas_uri():On Python >= 3.13 this already works today. On older Python versions our
from_uri()backport was broken, which is fixed in the next release (0.3.11). In 0.4.0,
UPath.from_uri(uri)will also followpathlib.Path.from_uri()forfile:URIs (itcurrently behaves like
UPath(uri)). We also documented the difference between the twostring forms.
Longer term it would be nice if fsspec interpreted the authority of
file://URIs; I'llraise that upstream.
Closing via #574, and closing #564 in favour of it.
Thanks again!