File URLs (file:///)

File URLs reference files on the local filesystem. They're used for local development and offline HTML files, but have significant security restrictions in browsers.

The short answer: on Linux and macOS, put file:// in front of the absolute path; on Windows, put file:/// in front of the drive letter and turn backslashes into forward slashes. Percent-encode spaces in both cases. /home/me/notes.txt becomes file:///home/me/notes.txt, and C:\Users\Me\My File.pdf becomes file:///C:/Users/Me/My%20File.pdf. Opening the file in a browser shows its file URL in the address bar.

While you might occasionally open local HTML files directly in a browser, file:// URLs come with significant limitations. Understanding these restrictions helps you avoid frustrating debugging sessions when your local files don't work as expected.

"A file URI identifies an object (a "file") stored in a structured object naming and accessing environment on a host (a "file system")."

File URL Structure

File URLs point to resources on your local filesystem. The format varies between operating systems, particularly for Windows drive letters and network shares.

# File URL format
file://[host]/path

# Unix/Mac examples:
file:///home/user/document.txt
file:///Users/name/Documents/file.pdf
file:///tmp/data.json

# Windows examples:
file:///C:/Users/name/Documents/file.txt
file:///C:/Program%20Files/App/config.json

# Network share (Windows UNC):
file://server/share/file.txt

# Components:
file://    - Scheme
[host]     - Optional hostname (usually empty for local)
/path      - Absolute path to file

Notice the three forward slashes after file:—two for the scheme separator and one for the root of the filesystem. Windows paths need the drive letter after the third slash, converting backslashes to forward slashes.

The path format differs significantly between operating systems. Let's look at the specific patterns for each platform.

Platform Differences

This table shows how the same type of file reference translates to a file URL on different operating systems. Getting these conversions right is important for cross-platform applications.

Windows UNC paths for network shares use the host component of the URL (the part between file:// and the path). This is the only common case where file URLs include a hostname.

Converting between filesystem paths and file URLs requires handling platform-specific quirks. Let's look at how to do this correctly.

Path to URL Conversion

Node.js provides built-in functions for path conversion that handle platform differences automatically. In browser environments, you'll need to implement the conversion yourself.

// Convert file path to file URL

// Node.js
const { pathToFileURL, fileURLToPath } = require('url');

// Path to URL
const filePath = '/home/user/documents/file.txt';
const fileUrl = pathToFileURL(filePath);
console.log(fileUrl.href);
// file:///home/user/documents/file.txt

// URL to path
const path = fileURLToPath('file:///home/user/file.txt');
console.log(path);
// /home/user/file.txt

// Windows path (on Windows, or with { windows: true } in Node 22+)
const winPath = 'C:\\Users\\name\\file.txt';
const winUrl = pathToFileURL(winPath, { windows: true });
console.log(winUrl.href);
// file:///C:/Users/name/file.txt

// Browser (limited)
function pathToFileUrl(path) {
  // Normalize path separators
  const normalized = path.replace(/\\/g, '/');

  // Ensure leading slash for Windows drive
  if (/^[a-z]:/i.test(normalized)) {
    return 'file:///' + normalized;
  }

  return 'file://' + normalized;
}

The Node.js pathToFileURL and fileURLToPath functions handle edge cases like special characters and drive letters correctly. The browser implementation shown is simplified and may need additional handling for production use.

The real challenge with file URLs is the strict security restrictions browsers impose. Let's examine what's blocked and why.

Browser Security Restrictions

Browsers treat file:// URLs as a special, restricted origin. Most network and storage APIs are blocked or limited to prevent local files from accessing sensitive data on your computer.

// file:// URLs have strict security restrictions

// ❌ Cannot fetch other file:// URLs
fetch('file:///path/to/data.json')
  .catch(err => console.log('Blocked:', err));
// Chrome: Fetch API cannot load file:///path/to/data.json.
//         URL scheme "file" is not supported.

// ⚠️ localStorage behaves differently
localStorage.setItem('key', 'value');
// Works in Chrome, but storage rules for file:// differ per browser

// ❌ Cannot use some Web APIs
navigator.serviceWorker.register('/sw.js');
// Service workers require HTTPS

// ⚠️ Cross-origin requests send Origin: null
fetch('https://api.example.com/data');
// CORS blocks it unless the server allows that origin

// ✅ Can load local resources from same directory
// <script src="script.js">
// <link href="style.css">
// <img src="image.png">

// ✅ Can use inline JavaScript and CSS

These restrictions exist because a malicious HTML file on your computer could otherwise read your private files or make requests on your behalf. The workaround is simple: use a local development server instead of opening files directly.

For web development, running a local server is almost always the better choice. Here's how to set one up with minimal effort.

Local Development

These one-liner commands start a local server serving files from the current directory. Your browser connects to localhost over HTTP, avoiding all the file:// restrictions while keeping everything local.

# Use a local server instead of file:// URLs

# Python
python -m http.server 8000
# Visit http://localhost:8000

# Node.js with http-server
npx http-server
# Visit http://localhost:8080

# PHP
php -S localhost:8000

# Live Server (VS Code extension)
# Right-click HTML file > "Open with Live Server"

# Vite
npx vite
# Visit http://localhost:5173

# Benefits of local server:
# - Proper CORS handling
# - Service workers work
# - localStorage works
# - Fetch API works
# - Closer to production behavior

Python's built-in HTTP server is the quickest option if you have Python installed. For JavaScript projects, Vite provides hot reloading and modern features. The VS Code Live Server extension adds a button right in your editor.

While browsers restrict file URLs, desktop applications built with Electron can use them safely with proper security configuration.

File URLs in Electron

Electron apps run with elevated privileges compared to regular web pages, so they can access local files. However, you should still follow security best practices to prevent vulnerabilities.

// Electron apps can use file:// URLs safely

const { app, BrowserWindow, protocol, net } = require('electron');
const path = require('path');
const { pathToFileURL } = require('url');

// Load local file in window
const win = new BrowserWindow();
win.loadFile('index.html');
// or
win.loadURL(`file://${__dirname}/index.html`);

// Register custom protocol (protocol.handle, Electron 25+;
// registerFileProtocol is deprecated). Call after app 'ready'.
protocol.handle('app', (request) => {
  const { pathname } = new URL(request.url);
  const root = path.join(__dirname, 'dist');
  const filePath = path.resolve(root, '.' + decodeURIComponent(pathname));
  // Reject paths that escape the app folder (app://x/../../secret)
  if (path.relative(root, filePath).startsWith('..')) {
    return new Response('Forbidden', { status: 403 });
  }
  return net.fetch(pathToFileURL(filePath).toString());
});

// Use custom protocol
win.loadURL('app://bundle/index.html');

// Security best practices:
// - Use contextIsolation: true
// - Use nodeIntegration: false
// - Validate file paths
// - Don't load remote content with file:// privileges

The custom protocol registration creates an app:// scheme that maps to local files while providing better security than raw file:// URLs. Always enable contextIsolation and disable nodeIntegration for renderer processes.

For web applications that need file access, browsers now offer the File System Access API—a secure, user-controlled alternative to file URLs.

Programmatic File Access

The modern File System Access API provides sandboxed file access without needing file:// URLs. The user explicitly grants access through a file picker, making this approach secure by design.

// Modern File System Access API (Chrome)
// Requires user interaction, not file:// URLs

// Open file picker
async function openFile() {
  const [fileHandle] = await window.showOpenFilePicker();
  const file = await fileHandle.getFile();
  const contents = await file.text();
  return contents;
}

// Save file
async function saveFile(contents) {
  const handle = await window.showSaveFilePicker({
    types: [{
      description: 'Text files',
      accept: { 'text/plain': ['.txt'] }
    }]
  });

  const writable = await handle.createWritable();
  await writable.write(contents);
  await writable.close();
}

// Open directory
async function openDirectory() {
  const dirHandle = await window.showDirectoryPicker();

  for await (const entry of dirHandle.values()) {
    console.log(entry.name, entry.kind);
  }
}

This API requires user interaction—you can't access files without the user clicking a button and selecting them. The file handle can optionally be stored in IndexedDB for persistent access (with user permission). The picker methods (showOpenFilePicker, showSaveFilePicker, showDirectoryPicker) are only available in Chromium browsers; Firefox and Safari implement just the origin private file system part of the API (navigator.storage.getDirectory()).