pypa/pip · error · ValueError

non-local file URIs are not supported on this platform: {url

Error message

non-local file URIs are not supported on this platform: {url!r}

What it means

ValueError from url_to_path when a `file:` URL contains a non-empty, non-'localhost' netloc (authority) and pip is not running on Windows. On non-Windows, only local file URLs (file:///abs/path or file://localhost/...) are convertible to a path; a remote host in the authority is rejected. On Windows, the same form is interpreted as a UNC share.

Source

Thrown at src/pip/_internal/utils/urls.py:39

    """
    Convert a file: URL to a path.
    """
    import urllib.request

    assert url.startswith(
        "file:"
    ), f"You can only turn file: urls into filenames (not {url!r})"

    _, netloc, path, _, _ = urllib.parse.urlsplit(url)

    if not netloc or netloc == "localhost":
        # According to RFC 8089, same as empty authority.
        netloc = ""
    elif WINDOWS:
        # If we have a UNC path, prepend UNC share notation.
        netloc = "\\\\" + netloc
    else:
        raise ValueError(
            f"non-local file URIs are not supported on this platform: {url!r}"
        )

    path = urllib.request.url2pathname(netloc + path)

    # On Windows, urlsplit parses the path as something like "/C:/Users/foo".
    # This creates issues for path-related functions like io.open(), so we try
    # to detect and strip the leading slash.
    if (
        WINDOWS
        and not netloc  # Not UNC.
        and len(path) >= 3
        and path[0] == "/"  # Leading slash to strip.
        and path[1] in string.ascii_letters  # Drive letter.
        and path[2:4] in (":", ":/")  # Colon + end of string, or colon + absolute path.
    ):
        path = path[1:]

View on GitHub (pinned to d7d0d0a394)

Solutions

On Linux/macOS, use a fully-local file URL: `file:///abs/path/pkg.tar.gz`.
If you need a network share, mount it locally first, then reference the mount point.
On Windows, the UNC form works; otherwise switch to http(s):// served by a simple index.
Verify with: `python -c "from urllib.parse import urlsplit; print(urlsplit('file://host/x'))"`.

Example fix

// before
pip install 'file://nas/share/pkg.tar.gz'   # on Linux

// after
# mount the share, then use a local path:
pip install '/mnt/nas/share/pkg.tar.gz'
# or a fully-local URL:
pip install 'file:///mnt/nas/share/pkg.tar.gz'

Defensive patterns

Strategy: validation

Validate before calling

import sys
from urllib.parse import urlsplit

def is_local_file_url(url: str) -> bool:
    if not url.startswith('file:'):
        return False
    netloc = urlsplit(url).netloc
    if sys.platform.startswith('win'):
        return True  # UNC path form supported
    return netloc in ('', 'localhost')

Type guard

null

Try / catch

null

Prevention

Prefer `file:///abs/path` (three slashes, no host) on Linux/macOS.
Mount network shares locally rather than using file://host/.
Validate URLs in your install scripts before passing them to pip.
On Windows, keep UNC shares or switch to an http index.

When it happens

Trigger: Passing a URL like `file://server/share/pkg.tar.gz` (with a host) to pip on Linux/macOS. urlsplit yields a netloc of 'server' which is neither empty nor 'localhost', and since WINDOWS is False, ValueError is raised.

Common situations: Trying to install from a UNC/SMB path using file://server/... on Linux; copy-pasting a Windows file URL onto a Linux CI runner; misconfigured index URL.

Related errors

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/9382d1b94c9a58df.json. Report an issue: GitHub.