file URI scheme

file is a Uniform Resource Identifier (URI) scheme used to identify a resource in a file system.

Format

A file URI has the format

file://host/path

where host is the fully qualified domain name of the system on which the path is accessible, and path is a hierarchical directory path of the form directory/directory/.../name. If host is omitted, it is taken to be "localhost", the machine from which the URL is being interpreted. Note that when omitting host, the slash is not omitted (while "file:///piro.txt" is valid, "file://simpen.txt" is not, although some interpreters manage to handle the latter).

RFC 3986 includes additional information about the treatment of ".." and "." segments in URIs.

Number of slash characters

• The character sequence of two slash characters (//) after the string file: denotes that either a hostname or the literal term localhost follows, although this part may be omitted entirely, or may contain an empty hostname.
• The single slash between host and path denotes the start of the local-path part of the URI and must be present.
• A valid file URI must therefore begin with either file:/path (no hostname), file:///path (empty hostname), or file://hostname/path.
• file://path (i.e. two slashes, without a hostname) is never correct, but is often used.
• Further slashes in path separate directory names in a hierarchical system of directories and subdirectories. In this usage, the slash is a general, system-independent way of separating the parts, and in a particular host system it might be used as such in any pathname (as in Unix systems).

There are two ways that Windows UNC filenames (such as \\server\folder\data.xml) can be represented. These are both described in RFC 8089, Appendix E as "non-standard". The first way (called here the 2-slash format) is to represent the server name using the Authority part of the URI, which then becomes file://server/folder/data.xml. The second way (called here the 4-slash format) is to represent the server name as part of the Path component, so the URI becomes file:////server/folder/data.xml. Both forms are actively used. Microsoft .NET (for example, the method new Uri(path)) generally uses the 2-slash form; Java (for example, the method new URI(path)) generally uses the 4-slash form. Either form allows the most common operations on URIs (resolving relative URIs, and dereferencing to obtain a connection to the remote file) to be used successfully. However, because these URIs are non-standard, some less common operations fail: an example is the normalize operation (defined in RFC 3986 and implemented in the Java java.net.URI.normalize() method) which reduces file:////server/folder/data.xml to the unusable form file:/server/folder/data.xml.

Examples

Unix

Here are two Unix examples pointing to the same /etc/fstab file on the host's local file system:

file://localhost/etc/fstab
file:///etc/fstab

The KDE environment uses URIs without an authority component:

file:/etc/fstab

Windows

Here are some examples which may be accepted by some applications on Windows systems, referring to the same, local file C:\WINDOWS\clock.avi

file://localhost/c:/WINDOWS/clock.avi
file:///c:/WINDOWS/clock.avi

Note that the drive letter followed by a colon and slash is part of the acceptable file URI.

Implementations

Windows

On Microsoft Windows systems, the normal colon (:) after a device letter has sometimes been replaced by a vertical bar (|) in file URLs. This reflected the original URL syntax, which made the colon a reserved character in a path part.

To access a file "the file.txt", the following might be used.

For a network location:

file://hostname/path/to/the%20file.txt

Or for a local file, the hostname is omitted, but the slash is not (note the third slash):

file:///c:/path/to/the%20file.txt

If a local file is instead accessed by using the form of the hostname example, but substituting hostname with the string "localhost" or a dot ("."), the URI will be converted to a UNC path, in the form \\localhost\c:\path\to\the file.txt or \\.\c:\path\to\the file.txt. In such a case, if the filepath is absolute (beginning with a drive letter designation), then this will not work in the localhost case, since the colon is not allowed in a share name, though will work for the "dot" case so long as the file is actually and not on a share. For example file://./sharename/path/to/the%20file.txt will not work, because it will result in sharename being interpreted as part of the DOSDEVICES namespace, not as a network share.

Web pages

File URLs are rarely used in Web pages on the public Internet, since they are only useful if it is known that a specific file exists on the designated host or the local computer. Additionally, web browsers generally disable File URLs in web pages that were not themselves loaded from a File URL for security reasons.

The host specifier can be used to retrieve a file from an external source. However, no specific file-retrieval protocol is specified and the interpretation of the host specifier is not well standardized, so it is only useful in specific circumstances.