pypa/pip · error · ValueError

non-local file URIs are not supported on this platform

Error message

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

What it means

Raised by url_to_path() when converting a file: URL to a local filesystem path on a non-Windows platform and the URL contains a non-empty, non-localhost network location (host). Only Windows supports UNC-path file URIs (file://host/share); on Linux/macOS any host component other than localhost is rejected.

Solutions

Mount the network share locally and use a plain file:/// or absolute path URL instead
If on Windows, ensure the UNC path syntax is correct (file://server/share)
Use an https index or a local directory path rather than a host-based file URL
For a localhost reference, use 'file://localhost/path' or 'file:///path'

Example fix

// before (on Linux/macOS)
pip install file://nas.example.com/shared/pkg-1.0.whl
// after
# mount the share, then reference the local path
pip install /mnt/nas/shared/pkg-1.0.whl
# or use file:// with empty/localhost authority
pip install "file:///mnt/nas/shared/pkg-1.0.whl"

Defensive patterns

Strategy: validation

Validate before calling

import urllib.parse, sys

def file_url_is_local(url: str) -> bool:
    parsed = urllib.parse.urlsplit(url)
    if parsed.scheme != 'file':
        return True  # not a file URL, different concern
    netloc = parsed.netloc
    if not netloc or netloc == 'localhost':
        return True
    return sys.platform == 'win32'

# before converting a file URL to a path
if not file_url_is_local(url):
    raise ValueError(f'non-local file URI not supported on this platform: {url}')

Type guard

import urllib.parse, sys

def is_supported_file_uri(url: str) -> bool:
    p = urllib.parse.urlsplit(url)
    return p.scheme != 'file' or not p.netloc or p.netloc == 'localhost' or sys.platform == 'win32'

Try / catch

from pip._internal.utils.urls import url_to_path

try:
    path = url_to_path(url)
except ValueError as e:
    if 'non-local file URIs' in str(e):
        # switch to a mounted local path or https index
        raise ConfigError(f'use a local or https URL instead of: {url}')
    raise

Prevention

Use 'file:///' (empty host) or absolute paths for local files on Linux/macOS
Reserve host-based file:// URLs for Windows UNC shares only
Mount network shares and reference local mount points
Validate file URLs for empty/localhost netloc before passing to pip

When it happens

Trigger: Calling url_to_path() with a URL like 'file://nas/share/package.whl' where the netloc ('nas') is neither empty nor 'localhost', and the platform is not Windows. The function is used internally when pip resolves a file: URL requirement.

Common situations: Referencing a package on a network share via a file://host/path URL on Linux or macOS. Misconfigured index URL using file:// with a hostname. Confusing a UNC path (Windows-only) with a generic file URL.

Related errors

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

Appendix: 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 f399c37189)