Skip to content

UNC paths are broken when parsing file:// URIs (authority ignored, round-trip fails) #557

Closed

Description

@t-onoz

Title

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.


Reproduction

from upath import UPath

p = UPath(r'\\server\share\file')
uri = p.as_uri()
print(uri)
# 'file://server/share/file'

p2 = UPath(uri)
print(p2)
# 'file://C://server/share/file'

Expected behavior

file://server/share/file represents a UNC path and should round-trip correctly:

UPath("file://server/share/file")
# -> WindowsUPath('//server/share/file')

Actual behavior

The authority (server) is dropped and interpreted as part of a local path:

FilePath('C://server/share/file', protocol='file')

This is not equivalent to the original UNC path.


Comparison with pathlib (Python 3.14)

from pathlib import Path

p = Path(r'\\server\share\file')
uri = p.as_uri()

Path.from_uri(uri)
# -> WindowsPath('//server/share/file')  # correct

pathlib correctly preserves UNC semantics, while UPath does not.


Impact

  • Round-trip is broken: p != UPath(p.as_uri())
  • UNC paths are corrupted
  • Produces invalid Windows paths

Suggested fix

When parsing file:// URIs:

  • If netloc (authority) is non-empty → treat as UNC:

    //{netloc}{path}
    
  • Otherwise → handle as a local path (file:///C:/...)


Environment

  • upath: 0.3.10
  • Python: 3.14
  • OS: Windows

Notes

I searched existing issues using:

  • "UNC"
  • "file URI"

but could not find a matching report.

Activity

  1. itzzdev09 commented on Sep 16, 2026

    @itzzdev09

    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.

  2. ap-- commented on Sep 17, 2026

    @ap--
    Collaborator

    Hi both,

    This is a bug yes. as_uri() should return file:////server/share/file in this case:

    pth = UPath(r'\\server\share\file')
    uri = pth.as_uri()
    assert uri == `file:////server/share/file`
    

    PR is welcome 🙏

    Cheers,
    Andreas ☺️

  3. t-onoz commented on Oct 3, 2026

    @t-onoz
    Author

    @ap--
    In stdlib pathlib , as_uri() returns file://server/share/file . Is file:////server/share/file really correct?

    from pathlib import Path
    pth = Path(r"\\server\share\file")
    
    print(repr(pth))
    # -> WindowsPath('//server/share/file')
    
    print(repr(pth.as_uri()))
    # -> 'file://server/share/file'
  4. ap-- commented on Nov 10, 2026

    @ap--
    Collaborator

    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:

    ("file://remote/share/pth", "{cwd}/remote/share/pth"),
    ("file:////remote/share/pth", "//remote/share/pth"),

    So there are two kinds of file: strings:

    PosixUPath / WindowsUPath FilePath (fsspec based)
    to string p.as_uri(): RFC 8089 file URI, same as pathlib str(p): fsspec urlpath
    from string UPath.from_uri(uri) / WindowsUPath.from_uri(uri) UPath(urlpath)

    The fix for your use case is to use from_uri(), the inverse of as_uri():

    from upath import UPath
    from upath.implementations.local import WindowsUPath
    
    p = UPath(r"\\server\share\file")
    assert WindowsUPath.from_uri(p.as_uri()) == p

    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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions