Browser Extension

The Motrix browser extension sends downloads to the local Motrix App or a remote Motrix Server and lets you check progress and manage tasks from the extension. It can also find video, audio, and images already loaded by a page and send supported streams to Motrix for downloading and merging.

Install Motrix Extension#

Use Motrix Extension with Motrix 2. Install Chrome, Microsoft Edge, and Firefox extensions from their stores; download the macOS Safari extension separately from GitHub Releases:

• Chrome: Install from the Chrome Web Store.
• Microsoft Edge: Install from Microsoft Edge Add-ons.
• Firefox: Install from Firefox Add-ons.
• Safari (macOS): Download the Safari extension (prerelease), then follow the steps below.

For development builds, see the build and manual loading instructions in the extension repository.

Safari on macOS#

The Safari extension is currently a prerelease distributed through GitHub Releases. It is signed and Apple-notarized, and supports Apple silicon and Intel Macs running macOS 13 or later. It is not a Mac App Store release and is not included in the Motrix desktop package.

1. Open the Safari download page. Under the release’s Assets, download the package ending in safari-macos-universal.zip and extract it.
2. Move Motrix Extension for Safari.app to Applications and open it. Keep a single installed copy.
3. Enable Motrix Extension in Safari → Settings → Extensions and grant access to the websites you use as needed. This signed version does not require Allow Unsigned Extensions.
4. For local connections, install a signed macOS release of Motrix 2 beta.44 or later from the download page. Open the installed Motrix.app you intend to use and complete first-launch setup. These releases include Safari’s desktop bootstrap service; approve its background item in System Settings if macOS requests it.
5. Open the extension from Safari’s toolbar and complete pairing as described below. Upgrading from a development build may require fresh pairing. For a remote backend, follow Connect to Motrix Server.

If Safari launches an older Motrix copy, open the intended installed Motrix.app again to update bootstrap registration. Downloading a new copy alone does not update registration; there is no need to delete the database or pairing credentials. Unsigned development builds cannot establish this production registration.

Setting it up#

1. Install the extension using the matching browser link above. For Safari, complete installation and enablement in the previous section first. Then manually launch Motrix 2 on this computer. Review the first-launch terms and, if you agree, accept them and continue to the main window before pairing.
2. Allow the connection in Motrix. The switch Connect browser extensions in Settings → Integration → Browser extensions is on by default. Windows and macOS installers, and Linux DEB/RPM packages, register the Native Messaging host for Chrome, Edge, and Firefox automatically. Safari uses the desktop bootstrap service described above; Flatpak requires the separate installation described below.
3. Start pairing. Open the extension and click Pair. The desktop edition discovers Motrix on this computer automatically; choose the correct instance if it finds more than one.
4. Enter the pairing code. Motrix shows the browser, extension identity, and an eight-character code. Confirm that you started the request, then enter that code in the extension. Deny a suspicious request in Motrix; an untouched request expires automatically.

Approved browsers appear under Connected extensions, each with a Last active time and a Disconnect button — disconnecting is also how you force a fresh pairing.

If local pairing fails#

First, open Motrix manually and complete first-launch setup. If the terms screen is still open, review and accept the terms if you agree, then wait for the main window before retrying in the extension. Motrix initializes its services after this step, so installing the app alone is not enough for local pairing.

If you installed Motrix through Homebrew and pairing still fails, try the Motrix 2 package from the official GitHub Releases. Open the newly installed app, complete first-launch setup, and retry pairing.

If pairing still fails, click Diagnose in the extension’s connection error panel. Copy the report with the small copy button at its top right and include it when reporting the issue. For an unpacked development extension, also check that its current extension ID is trusted in Motrix and included in the Native Host allowlist. The Flatpak companion registers only the built-in official extension IDs; adding a custom ID in Motrix does not update its browser manifests.

Connect to Motrix Server#

A remote Server does not use the desktop app’s native-messaging discovery path. Its administrator must first upgrade to a Server build with remote MBP1 support and explicitly enable the remote browser-extension routes. The Server startup log prints the exact WS/WSS address to enter. Add that address in the extension’s Server settings and start pairing. The Motrix web UI displays an eight-character code; enter it in the extension to authenticate.

After pairing, enable Remote downloads for that Server under the extension’s Settings → Integration. Cookies and page-derived request headers are disabled for remote Servers by default; grant them separately for that Server only when needed.

See Motrix Server (Docker) for the settings, the WS/HTTP risk acknowledgement for NAS deployments, and WSS reverse-proxy paths.

What you can send#

• Regular files — the extension can include the request headers and cookies a download needs, depending on the download path and your permissions. Authenticated downloads and temporary links can still fail when a session or link expires.
• Streaming video (HLS/DASH) — Motrix downloads the segments, then combines audio and video with FFmpeg into one file. FFmpeg is managed under Settings → Integration → Media tools (Motrix uses the bundled copy, a custom path, or the system installation — the card shows which).
• Magnet links — handed straight to the torrent workflow.

Clicking send twice by accident is fine — duplicate requests for the same download are ignored.

If a handoff fails#

The extension surfaces Motrix’s actual reason, in plain words:

Message	What it means
“Live streams cannot be downloaded”	The video is a live broadcast, not a finished file
“DRM-protected content cannot be downloaded”	The content is encrypted with DRM — Motrix will not bypass it
“Session expired — refresh the page in your browser and try again”	Your login on the site ran out mid-handoff
“ffmpeg failed while combining audio and video”	The final merge failed — check Media tools for FFmpeg status
“Resume failed; restart the download”	The server refused to continue a partial file

Trusted extensions (advanced)#

Under Trusted extensions you can authorize a third-party extension to talk to Motrix: click Add extension, paste its extension ID, and pick the browser (Chrome/Edge or Firefox). As the settings screen itself notes, most people never need this — the official extension is trusted out of the box.