About

The file: URI scheme (RFC 8089) maps local filesystem paths to URLs, but manual conversion introduces encoding errors that break tooling, build scripts, and browser resource loading. A bare space character in /Users/my projects/ must become %20; a Windows backslash \ must become /; a drive letter C: must appear as /C: after the authority. Getting any of these wrong produces a malformed URI that silently fails in fetch(), Electron loadURL(), or CSS url() references. This tool performs segment-by-segment percent-encoding per RFC 3986 §2.1, normalizes path separators, resolves relative segments (. and ..), and handles UNC paths. It approximates the behavior of Node.js url.pathToFileURL(path). Limitation: browser-side resolution uses a configurable virtual working directory since no real filesystem access exists.

Formulas

The conversion follows a deterministic pipeline of three stages applied to the raw input string P:

fileURL(P) = "file://" + authority + encode(normalize(resolve(P)))

Stage 1 - resolve(P): If resolve mode is enabled, relative paths are joined with the virtual CWD. Segments . (current) and .. (parent) are collapsed per POSIX rules. Tilde ~ expands to CWD base.

Stage 2 - normalize: All backslashes \ become forward slashes /. Windows drive letters are detected via regex /^[A-Za-z]:/ and prefixed with /. UNC paths //server/share place server in the URI authority field.

Stage 3 - encode: Each path segment is individually percent-encoded using encodeURIComponent, which encodes all characters except A-Z a-z 0-9 - _ . ~. Slash separators are preserved verbatim. Already-present % signs are encoded as %25 to prevent double-encoding ambiguity.

Where: P = raw filesystem path string. authority = empty string for local files, or hostname for UNC paths. encodeURIComponent follows RFC 3986 §2.1 percent-encoding.

Reference Data

Input Path	OS	Resolved	Output file:// URL
/Users/pony/unicorn.jpg	POSIX	No	file:///Users/pony/unicorn.jpg
unicorn.jpg	POSIX	Yes (CWD: /home/dev)	file:///home/dev/unicorn.jpg
C:\Users\pony\pic.jpg	Windows	No	file:///C:/Users/pony/pic.jpg
\\server\share\file.txt	Windows	No	file://server/share/file.txt
./docs/../readme.md	POSIX	Yes (CWD: /project)	file:///project/readme.md
/path/with spaces/file.txt	POSIX	No	file:///path/with%20spaces/file.txt
/unicode/café/naïve.txt	POSIX	No	file:///unicode/caf%C3%A9/na%C3%AFve.txt
D:\My Docs\résumé.pdf	Windows	No	file:///D:/My%20Docs/r%C3%A9sum%C3%A9.pdf
/tmp/file#1.log	POSIX	No	file:///tmp/file%231.log
/var/data/100%.csv	POSIX	No	file:///var/data/100%25.csv
relative/path/index.html	POSIX	No	file:///relative/path/index.html
C:\Program Files (x86)\app.exe	Windows	No	file:///C:/Program%20Files%20(x86)/app.exe
/already%20encoded/file.txt	POSIX	No	file:///already%2520encoded/file.txt
~/Documents/note.md	POSIX	Yes (CWD: /home/user)	file:///home/user/Documents/note.md
.	POSIX	Yes (CWD: /srv/app)	file:///srv/app

Frequently Asked Questions

A literal percent sign in a filename (e.g., '100%.csv') must be encoded as %25 in a valid URI per RFC 3986 §2.4. If the tool preserved existing percent sequences, it could not distinguish between a literal "%20" in a filename and an already-encoded space. The safe default is to treat all input as raw filesystem characters and encode them uniformly. If your path is already partially encoded, decode it first before converting.

UNC paths place the server hostname in the URI authority component. A path like \\fileserver\docs\report.pdf becomes file://fileserver/docs/report.pdf rather than file:///fileserver/docs/report.pdf (note two slashes before the host, not three). This follows RFC 8089 §2, Appendix B. The tool auto-detects UNC paths by checking for a leading double-backslash or double-forward-slash pattern.

All non-ASCII characters are UTF-8 encoded then percent-encoded per RFC 3986. For example, "café" becomes "caf%C3%A9" because "é" is U+00E9, which in UTF-8 is the two-byte sequence 0xC3 0xA9. JavaScript's encodeURIComponent handles this natively. The resulting file URL is valid in all modern browsers and Node.js.

Browsers have no access to your filesystem or current working directory for security reasons. The virtual CWD simulates what Node.js path.resolve() does: joining a relative path with the current directory to produce an absolute path. Set the virtual CWD to match your actual project directory for accurate results. When resolve mode is disabled, relative paths are treated as absolute from the filesystem root.

Yes. The output conforms to RFC 8089 and RFC 3986, which are the standards browsers use to parse file: URLs. The per-segment encoding ensures that special characters like spaces, hash signs, and question marks do not break URL parsing. Note that most browsers block file: URLs loaded from http/https pages due to mixed-content security policies. File URLs work when the HTML document itself is opened via file: protocol or in Electron/desktop contexts.

When resolve mode is on, dot segments are collapsed per POSIX rules: /a/b/../c becomes /a/c, and /a/./b becomes /a/b. Trailing slashes are preserved because they can be semantically meaningful (indicating a directory). When resolve mode is off, no normalization of . or .. occurs; only backslash-to-slash conversion and percent-encoding are applied.