Motrix

A modern, full-featured download manager that stays simple to use

English | 简体中文

Overview

Motrix is a clean, full-featured desktop download manager for HTTP, FTP, BitTorrent, magnet links, and more.

Motrix Turbo is Motrix v2, rebuilt from the ground up with Electron, React, and TypeScript while keeping the clean, straightforward experience of v1. The download core is independent of the UI. Browser extensions and command-line tools communicate with the app over MDXP (Motrix Download eXchange Protocol), an open protocol built on JSON-RPC 2.0, while plugins run in isolated sandboxes.

The same core powers two ways to run Motrix:

• Desktop app: Runs on macOS, Windows, and Linux
• Headless server: Runs without a desktop environment, either directly on Node.js or in Docker, and includes a web UI for NAS devices and home servers

✨ Features

• 🕹 Clean, intuitive interface with dark mode
• 🦄 BitTorrent downloads with per-file selection, plus magnet link support
• 📡 Built-in tracker list management with automatic updates and health checks
• 🔌 UPnP and NAT-PMP port mapping
• 🚥 Upload and download limits with multiple speed-limit profiles
• 💾 SQLite-backed sessions that restore downloads after a restart
• 📊 Customizable Dashboard with transfer stats, live activity, and task tiles
• 🔔 System notifications when downloads finish, plus an in-app notification center
• 🧩 QuickJS-based plugin sandboxing, fine-grained permissions, and an in-app marketplace
• 🌐 Chrome and Firefox extensions that hand browser downloads off to Motrix in one click
• ⌨️ Official @motrix/cli client for everyday shell use and AI agents
• 🐳 Docker-ready headless server with secure device-code pairing for remote clients
• 🎬 Extensible URL Resolver plugins for extracting media from supported sites
• 🤖 System tray integration and launch at startup
• 🌍 Simplified Chinese and English UI, with more languages planned
• 🔗 Handlers for motrix:// and magnet: links, plus .torrent file associations

🧩 Ecosystem

Motrix extends beyond the desktop app with a shared protocol library, command-line client, browser extensions, and a complete plugin toolchain:

Project	Distribution	What it does
@motrix/mdxp	npm package	Defines the shared JSON-RPC 2.0 wire schemas and Zod types for MDXP, with helpers for bidirectional connections
@motrix/cli	npm package	Provides the motrix command, automatically discovers a local desktop app, and pairs with remote instances
Motrix Browser Extension	Browser extension	Intercepts downloads in Chrome and Firefox (Manifest V3), hands them off to Motrix, and pairs securely with the desktop app over native messaging
Motrix Plugin SDK	Four npm packages	Includes @motrix/plugin-manifest-schema, @motrix/plugin-api, @motrix/plugin-cli, and create-motrix-plugin for developing, testing, and packaging plugins
Builtin Plugins	Signed .moext packages	Includes three official plugins: Filename Template for renaming files from a template before they are saved, Page Scraper for extracting direct file links from HTML pages, and URL Resolver as the foundation for site-specific media resolution
Plugin Registry	Public JSON feed	Publishes plugin listings and install metadata at dl.motrix.app/registry/plugins.json for both the website and the in-app marketplace

CLI quick start

npm install -g @motrix/cli    # Requires Node.js 22 or later

motrix add https://example.com/file.iso --save-dir ~/Downloads
motrix list                   # List downloads
motrix watch --stats          # Stream live progress as NDJSON
motrix pair --name my-nas     # Pair with a remote or headless instance

Build a plugin

pnpm create motrix-plugin my-plugin

Plugins run inside a QuickJS sandbox. Each plugin declares the host capabilities it needs in its manifest, such as notifications, secret storage, or FFmpeg detection. Motrix asks the user before granting access. See the Plugin SDK documentation for development workflows, starter templates, packaging, and publishing.

📦 Installation

Desktop app

Download Motrix from motrix.app and choose the package for your operating system. Most Mac users should choose the Apple Silicon build; Intel builds are available for older Macs with Intel processors.

Available package formats:

Platform	Formats	Recommendation
macOS	.dmg / .zip	The Apple Silicon .dmg is recommended; use the Intel build only on an Intel-based Mac
Windows	.exe (NSIS installer) / .zip	The .exe installer is the best choice for most users; use .zip for a manually extracted copy
Linux	.AppImage / .deb / .rpm, plus Flatpak and Snap	Use .deb on Debian or Ubuntu, .rpm on Fedora or openSUSE, or .AppImage to run Motrix without installing it

Command-line client

npm install -g @motrix/cli

You can also install it from Settings → Integration → Command-line tools in the desktop app.

Headless server with Docker

The repository includes a Dockerfile that builds an image with the web UI and aria2 included:

docker build -t motrix-turbo:dev .

Remote clients such as the CLI and browser extensions pair with the server through a device-code flow. See the Dockerfile and related documentation for details.

🛠 Development

Development requires Node.js 22 or later and pnpm. Use the pnpm version specified by the packageManager field in package.json.

git clone https://gitlab.com/agalwood/motrix-turbo.git
cd motrix-turbo

pnpm install     # Install dependencies, download aria2 for your platform, and rebuild native modules
pnpm start       # Start the Electron app in development mode with Vite HMR in the renderer

pnpm test        # Run the Vitest unit tests
pnpm test:e2e    # Run the Playwright E2E tests
pnpm run lint    # Run Biome checks

pnpm build       # Fetch signed built-in plugins, then build the native host and four Vite targets

See the scripts in package.json for the available packaging commands. Platform-specific settings for macOS, Windows, and Linux live in electron-builder.json.

🔧 Tech stack

Area	Stack
Desktop shell	Electron 43
UI	React 19 + Tailwind CSS 4 + shadcn/ui
Language	TypeScript in strict mode
Build system	Vite 8 with separate main, preload, worker, and renderer targets
Validation	Zod 4 for settings, IPC payloads, and wire schemas
Download engine	A Motrix-maintained fork of aria2, bundled with the app
Persistence	better-sqlite3 for download session storage and recovery
Plugin sandbox	quickjs-emscripten
Server runtime	Node.js + Fastify + WebSocket
Internationalization	i18next + react-i18next
Quality tooling	Biome, Vitest, and Playwright

The codebase has four strict layers. CI enforces the dependency boundaries between them, keeping the core portable and leaving a clear path for a future Rust rewrite:

renderer (React UI)
   │  IPC via window.motrix
app core (tasks, settings, plugins, bridge)
   │
engine adapter
   │
aria2 (download engine)

The Electron desktop app and the Node.js headless server share the same core. Platform-specific capabilities such as notifications and secret storage have separate implementations with consistent behavior.

📜 License

MIT © 2018-present Dr_rOot

See THIRD_PARTY_NOTICES.md for third-party license information. Release packages also include a generated dependency inventory, consolidated license texts, and an SPDX 2.3 SBOM under legal/.