The "file" URI Scheme
updated by
- rfc-9844 — Entering IPv6 Zone Identifiers in User Interfaces
updates
- rfc-1738 — Uniform Resource Locators (URL)
Extracted elements (20)
The file URI scheme is intentionally not coupled with a specific protocol or media type. This allows it to be used in discussions about files independently of the access mechanism, while actual dereferencing is only reliable for local files.
The syntax definition in Section 2 makes the entire authority component, including double slashes "//", optional. This differs from RFC 1738, which required file URLs to always start with "file://" followed by a (possibly blank) host name. The change accommodates the minimal form "file:/path/to/file" found in widespread practice.
The syntax is derived from the generic URI syntax of RFC 3986, which postdates previous file URI specifications in RFC 1630 and RFC 1738. Where incompatibilities arise they are usually in parts that were underspecified in earlier definitions and have been tightened by more recent specifications.
A file URI can be dependably dereferenced or translated to a local file path only if it is local—meaning it has no file-auth, or the file-auth is "localhost", or a fully qualified domain name resolving to the local machine. Operations on non-local file URIs are neither defined nor forbidden by this specification.
Several nonstandard syntax variations exist in practice but are not supported by the normative syntax: user information in the authority (for VMS paths), DOS/Windows drive letters, vertical line character in place of colon in drive letters, UNC strings mapped to authority or path, and backslash as path separator.
Some usages have copied Windows file paths with backslash separators directly into file URI path components, producing URIs with unencoded backslashes forbidden by RFC 1738 and RFC 3986. Such URIs may be updated by replacing all backslashes with forward slashes if it can be determined with reasonable certainty they are path separators.
The vertical line character "|" has historically appeared in place of ":" in drive letter constructs (e.g., "file:///c|/path/to/file"). RFC 3986 forbids this usage; to update such URIs, replace "|" with ":". Parsers needing to handle legacy URIs may use the extended drive-letter rule: drive-letter = ALPHA ":" / ALPHA "|".
The WHATWG URL specification defines browser behavior for file URIs as a living document, and its algorithms and syntax definitions may or may not be consistent with RFC 8089. Implementors sharing file URIs with browsers following WHATWG should be aware of possible discrepancies.
Any transport-related handling of the file URI scheme MUST retain the case of the path as given. Mapping to or from a case-insensitive form is solely the responsibility of the implementation processing the file URI on behalf of the referenced file system.
Users MAY choose to include an auth-path with no file-auth when creating a URI to maximize compatibility with previous specifications, since some implementations incorrectly interpret all authority values (including "localhost") as non-local.
When a file URI is produced representing textual data from the Unicode Standard, the data SHOULD be encoded as octets according to UTF-8 before percent-encoding is applied, as per Section 2.5 of RFC 3986.
For DOS- and Windows-like systems, the nonstandard local-path rule can include a drive-letter segment: local-path = [ drive-letter ] path-absolute, where drive-letter = ALPHA ":". URIs of the form "file:///c:/path/to/file" are already supported by path-absolute; "file:c:/path/to/file" requires this extension.
The file-auth component specifies the fully qualified domain name of the system on which the file is accessible, or the special string "localhost" meaning "the machine from which the URI is being interpreted." An auth-path with no file-auth is equivalent to using "localhost".
UNC filespace selector strings can be translated to file URIs by mapping hostname to the authority component and sharename+objectnames to the path, yielding URIs of the form "file://host.example.com/Share/path/to/file". Alternatively, UNC strings can be encoded entirely in the path, yielding forms like "file:////host.example.com/path/to/file".
This document registers the "file" URI scheme as a permanent entry in the IANA "Uniform Resource Identifier (URI) Schemes" registry, complying with BCP 35. The change controller is IETF and the contact is the Applications and Real-Time Area.
File systems assign operational meaning to special characters such as "/", "\", ":", "[", "]", and special device names like ".", "..", "aux", "lpt". Testing for existence of such names may cause OS pauses or unrelated system calls, leading to denial-of-service and unintended data transfer risks. Implementers should research reserved names for their storage devices.
File systems vary in case handling; care must be taken to avoid issues from unexpected aliasing due to case-only differences between file paths or URIs, or from mismatched encodings or Unicode equivalences (UAX15).
Historically, user agents have granted file URI scheme content a large amount of privilege, which can lead to privilege escalation attacks. The most secure option is to use globally unique identifiers as the origin for each file URI per RFC 6454; directory-based privileges have seen some success but are not widely adopted.
Treating a non-local file URI as local, or attempting to perform local operations on a non-local URI, can result in security problems. Implementations must correctly distinguish local from non-local URIs.
The file URI syntax is defined in ABNF as: file-URI = file-scheme ":" file-hier-part, where file-scheme = "file", file-hier-part = ( "//" auth-path ) / local-path, auth-path = [ file-auth ] path-absolute, local-path = path-absolute, and file-auth = "localhost" / host. The authority component including double slashes is optional.