ipfs:// in the Browser: How It Actually Works

Click an ipfs:// link in most browsers today and nothing happens, or worse, the browser tries to search for it as plain text. This series has covered gateways as the practical way IPFS content reaches a browser, but not why that workaround is necessary at all: browsers, with one narrow exception, simply don't understand the ipfs:// URI scheme natively, and the story of why, and what actually gets built to work around it, is its own piece of this ecosystem.

TL;DR:

• Almost no mainstream browser supports the ipfs:// and ipns:// URI schemes natively; Opera for Android is a rare exception, translating requests to a public gateway subdomain under the hood
• Chromium, the engine behind Chrome, Edge, and most other browsers, does not support manifest-based custom protocol handlers the way Firefox does, which is the core technical reason ipfs:// links mostly don't work out of the box
• IPFS Companion, a browser extension connecting to a locally running IPFS node, is the actual workaround: on Firefox it registers a real protocol handler, on Chromium it relies on a search-query interception trick instead, since a proper handler API isn't available there
• Because native support is this inconsistent, gateway URLs, https://gateway.example/ipfs/CID, became the practical, universally-working way to share IPFS content, working in any browser with zero extension or configuration required
• AIOZ Pin's gateway URLs exist for exactly this reason: they're the one link format guaranteed to work everywhere right now, regardless of whether a visitor has IPFS Companion installed or is using a browser that will never support ipfs:// at all

The Gap Between the URI Scheme and What Browsers Actually Do

ipfs://<CID> and ipns://<name> are real, defined URI schemes, the intended, native way to reference IPFS content the same way https:// references a web page. But defining a scheme and having browsers act on it are different things, and almost no mainstream browser ships built-in support for either one. Opera for Android is the notable exception, shipping native handling that translates an ipfs:// request to a URL on a public subdomain gateway behind the scenes, effectively doing automatically what this section's later coverage of gateway URLs describes doing manually everywhere else.

Why Chromium Is the Core of the Problem

The specific technical reason most browsers fall short traces back to Chromium, the engine underneath Chrome, Edge, and the majority of browsers in use today. Firefox supports registering custom protocol handlers declaratively, through a protocol_handlers entry in an extension's manifest, which is exactly the mechanism a browser extension needs to make ipfs:// links open correctly. Chromium doesn't support that manifest-based approach at all, which means the same clean solution simply isn't available to any extension running there, regardless of how well-built it is.

IPFS Companion: Two Different Solutions for Two Different Engines

IPFS Companion, a browser extension that connects to a locally running IPFS node, exists specifically to bridge this gap, and it has to solve the problem differently depending on which engine it's running in. On Firefox, it uses the real protocol_handlers mechanism, registering genuine handling for ipfs://, ipns://, and dweb: links. On Chromium, lacking that option, it falls back to a workaround: a user types or clicks an ipfs://CID link, the browser treats it as a search query since it doesn't recognize the scheme, and the extension intercepts that search, extracts the actual CID, and redirects to a gateway URL. It works, but it depends on the browser's search-handling behavior rather than a proper protocol registration, a meaningfully more fragile mechanism than what Firefox allows.

Why Gateway URLs Became the Practical Default

Given that inconsistency, an ipfs:// link can't be relied on to work for an arbitrary visitor: it depends on their specific browser, and on Chromium, on having a specific extension installed and configured correctly. A gateway URL sidesteps all of that entirely, since it's just a regular https:// link any browser already knows exactly how to handle, no extension, no protocol registration, no local node required. This is the practical reason gateway links, not ipfs:// links, are what actually gets shared in practice across the ecosystem, not a failure to adopt the "proper" scheme, but a direct response to how inconsistently browsers actually support it.

What About Other Chromium-Based Browsers Like Brave?

Brave, built on Chromium but known for shipping privacy and decentralization-adjacent features other Chromium browsers don't bother with, is a natural place to look for an exception to this pattern. As of this writing it isn't one: native ipfs:// handling has been an open, actively discussed request in Brave's own issue tracker rather than a shipped feature, running into the same underlying Chromium limitation described above rather than something Brave's own team can route around unilaterally. It's a useful data point either way, it shows the gap isn't a lack of interest from privacy-focused browser vendors, it's a real constraint at the engine level that individual browsers built on Chromium can't fully solve on their own.

Where AIOZ Pin's Gateways Fit This Picture

Every gateway URL this series has referenced, AIOZ Pin's dedicated gateways included, exists in the specific gap this article describes: the difference between what ipfs:// is supposed to do and what browsers will actually do with it today. A gateway link works identically whether a visitor is running Firefox with IPFS Companion installed, Chromium with nothing installed at all, or any other browser that will likely never ship native ipfs:// support. That universal compatibility, not a technical shortcut, is the entire reason gateway URLs are the link format that actually gets used.

Frequently Asked Questions

Do browsers support ipfs:// links natively? Almost none do. Opera for Android is a rare exception, translating the request to a public gateway subdomain automatically. Most other browsers, including Chromium-based ones, don't recognize the scheme at all.

Why doesn't Chrome support ipfs:// the way Firefox extensions can? Chromium doesn't support the manifest-based custom protocol handler mechanism Firefox uses, so an extension can't register real handling for the scheme there the same way it can on Firefox.

What does IPFS Companion actually do? It connects to a locally running IPFS node and bridges ipfs:///ipns:///dweb: links to it, using a real protocol handler on Firefox and a search-query interception workaround on Chromium, since that's the only option available there.

Why do people share gateway links instead of ipfs:// links? Because a gateway URL is a plain https:// link that works in any browser without an extension or configuration, while an ipfs:// link's behavior depends heavily on which browser and setup the recipient has.

Is ipfs:// support likely to improve across more browsers? The core limitation is Chromium's lack of manifest-based protocol handler support, which is outside any single extension's control; broader native support would need engine-level changes, not just extension updates.

Does AIOZ Pin's gateway depend on visitors having IPFS Companion installed? No. A gateway URL is a standard HTTP link that works in any browser as-is, which is exactly why gateway links, not raw ipfs:// links, are the practical way AIOZ Pin content actually gets shared and accessed.

Related Reading

• How IPFS Verifies Content Without Trusting the Gateway - the difference between a trusted gateway request and a self-verified one, both of which use the same gateway URLs covered here
• libp2p: The Networking Layer Underneath IPFS - the peer-to-peer connectivity a local IPFS node needs before IPFS Companion's Firefox integration can do anything
• IPNS: Mutable Pointers to Immutable IPFS Content - the ipns:// scheme this article's browser-support gap applies to as well
• Helia: IPFS's Modern JavaScript Implementation - the actual library a browser-based app runs to speak IPFS directly

References

• IPFS Docs: Install the IPFS Companion Browser Extension
• ipfs/in-web-browsers: Tracking native browser IPFS support