# Motrix User Guide

Motrix is a free, open-source, full-featured download manager for Windows, macOS, and Linux. It downloads over **HTTP, FTP, BitTorrent, and Magnet**, manages many tasks at once, and is built around the battle-tested [aria2](https://aria2.github.io/) download engine wrapped in a clean, modern interface.

This guide is written for people who **use** Motrix: how to install it, add and manage downloads, tune its behavior, and recover when something goes wrong. Every command, option, and label below is taken directly from Motrix's source code (version `1.8.19`).

> [!NOTE]
> Motrix has two audiences. This **User Guide** covers everyday use. If you are an administrator, packager, or developer — and want the architecture, the full aria2 option reference, the RPC/security model, or build and deployment details — read the companion **Admin Guide** at [Admin Guide](/guides/agalwood/Motrix/admin-guide/).

---

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [Installation](#2-installation)
3. [The Motrix Window at a Glance](#3-the-motrix-window-at-a-glance)
4. [Adding Downloads](#4-adding-downloads)
5. [Managing Tasks](#5-managing-tasks)
6. [BitTorrent & Magnet Downloads](#6-bittorrent--magnet-downloads)
7. [Preferences](#7-preferences)
8. [Common Tasks (Recipes)](#8-common-tasks-recipes)
9. [Keyboard Shortcuts](#9-keyboard-shortcuts)
10. [How Motrix Works (Concepts)](#10-how-motrix-works-concepts)
11. [Troubleshooting](#11-troubleshooting)
12. [FAQ](#12-faq)
13. [Reference](#13-reference)

---

## 1. Quick Start

Get your first download running in under a minute.

1. **Install Motrix** for your operating system (see [Installation](#2-installation)).
2. **Launch** Motrix. The main window opens on the **Downloading** task list.
3. **Add a download.** Press <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>N</kbd> (or click the **+** button). The **New Task** dialog appears.
4. On the **URL** tab, paste one or more links — **one task URL per line**. HTTP, HTTPS, FTP, and magnet links are all accepted.
5. (Optional) Choose where to save with **Save to**, or accept the default Downloads folder.
6. Click **Submit** (or press <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>Enter</kbd>).

Your download appears in the **Downloading** list with a live progress bar and speed. That's it.

> [!TIP]
> Motrix reads your clipboard when you open the New Task dialog. If your clipboard already contains a downloadable link (`http://`, `https://`, `ftp://`, or `magnet:`), it is auto-filled into the URL box for you.

---

## 2. Installation

Motrix ships as a native installer for each platform. Download the package for your OS from [GitHub Releases](https://github.com/agalwood/Motrix/releases) and install it. Package managers are also supported.

> [!NOTE]
> Motrix bundles its own copy of the aria2 download engine inside the application. You do **not** need to install aria2 separately.

=== "Windows"

    Recommended: install with the setup package (`Motrix-Setup-x.y.z.exe`) for the complete experience — torrent-file association and magnet-link capture are configured automatically.

    Using a package manager instead:

    ```powershell
    # Chocolatey
    choco install motrix
    choco upgrade motrix

    # Scoop (portable; requires Windows 7+)
    scoop bucket add extras
    scoop install motrix
    ```

    A **portable** build is also published — it runs without installation and keeps its data alongside the executable.

=== "macOS"

    Install with Homebrew:

    ```bash
    brew update && brew install motrix
    ```

    Or download the `.dmg` and drag Motrix into your **Applications** folder.

=== "Linux"

    Download the `AppImage` (works on all distributions) or install the `snap`:

    ```bash
    # Snap (Ubuntu and derivatives)
    sudo snap install motrix

    # Flatpak
    flatpak install flathub net.agalwood.Motrix
    flatpak run net.agalwood.Motrix

    # Arch (AUR)
    yay -S motrix
    ```

    `.deb` and `.rpm` packages are also available on the releases page.

> [!IMPORTANT]
> On Linux, Motrix may need to run with `sudo` the **first time** because it lacks permission to create the download session file (`/var/cache/aria2.session`). After the first run this is no longer required.

> [!CAUTION]
> If you are upgrading from a very old version (v1.6.11 or earlier), automatic updates will fail. Motrix changed its application bundle identifier in v1.8.0 (from `net.agalwood.Motrix` to `app.motrix.native`). Use the [Motrix Install Assistant](https://github.com/motrixapp/motrix-install-assistant) to migrate, or simply download and install the latest version manually.

### Verifying the install

Launch Motrix. If the main window opens and shows the **Downloading / Waiting / Stopped** task tabs, the bundled engine started correctly. If you instead see a system-error dialog on launch, the download engine failed to start — see [Troubleshooting](#error-the-download-engine-failed-to-start).

---

## 3. The Motrix Window at a Glance

Motrix's main window is organized around your **task lists**. The three lists are:

| List | Label | What it contains |
|------|-------|------------------|
| Active | **Downloading** | Tasks currently transferring data |
| Waiting | **Waiting** | Queued and paused tasks waiting their turn |
| Stopped | **Stopped** | Completed, errored, and removed tasks (your history) |

Switch between lists from the sidebar or with <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>L</kbd>. Each task row shows its name, size, progress, and real-time download/upload speed. Click a task to open **Task Details** with per-file, progress, and (for torrents) peer and tracker information.

Motrix also lives in your **system tray** (menu bar on macOS) for quick access even when the main window is hidden. On macOS the tray can display a live **speed meter**, and Motrix supports the **Touch Bar**.

> [!NOTE]
> When there are no tasks in the current list, Motrix shows *"There are no current tasks."* This is normal for a fresh install.

---

## 4. Adding Downloads

All downloads start from the **New Task** dialog. Open it with the **+** button, the **Task ▸ New Task** menu, or <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>N</kbd>. The dialog has two tabs: **URL** and **Torrent**.

### 4.1 Download from a URL (HTTP / HTTPS / FTP / Magnet)

1. Open the New Task dialog and stay on the **URL** tab.
2. Enter your links in the text box — **one task URL per line**. You can add many at once.
3. Set the options below as needed, then click **Submit**.

| Field | Label | Purpose |
|-------|-------|---------|
| URLs | *(main text box)* | One downloadable link per line. Supports `http`, `https`, `ftp`, and `magnet:` |
| Rename | **Rename** | Optional. Save the file under a different name (`out` option) |
| Splits | **Splits** | Number of parallel connections for this task (1 up to your *Maximum connections per server* setting) |
| Save to | **Save to** | Destination folder. Pick a recent/favorite directory or browse to a new one |

> [!TIP]
> **Splits** is the single most effective speed lever for a slow single-source download. Raising it tells aria2 to open multiple connections to the same server and download different byte ranges in parallel. The maximum is capped by your *Maximum connections per server* preference (default **64**).

#### Advanced per-task options

Tick **Advanced Options** at the bottom of the dialog to reveal per-task overrides. These apply only to the task you are adding:

| Option | Label | Use it when |
|--------|-------|-------------|
| User-Agent | **User-Agent** | A server blocks generic clients and you need to present as a browser |
| Authorization | **Authorization** | The download requires an `Authorization` header (e.g. a bearer token) |
| Referer | **Referer** | The server checks the referring page before serving the file |
| Cookie | **Cookie** | The resource sits behind a login/session cookie |
| Proxy | **Proxy** | Route just this task through a proxy: `[http://][USER:PASSWORD@]HOST[:PORT]` |
| Navigate to Downloading | *(checkbox)* | Jump to the Downloading list automatically after adding |

> [!NOTE]
> A **Copyright Warning** may appear when you add audio or video links: *"The file you want to download may be copyrighted audio or video, please ensure that you have permission to access it."* Confirm only if you have the right to download the content.

### 4.2 Download a Torrent file

1. Open the New Task dialog and switch to the **Torrent** tab.
2. **Drag a `.torrent` file** onto the drop zone, or click it to browse. (Prompt: *"Drag torrent file here, or click to select."*)
3. Motrix reads the torrent and shows its file list. **Select which files** to download — you don't have to take the whole torrent.
4. Set **Save to** and click **Submit**.

You can also open a torrent with **File ▸ Open Torrent File…** (<kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>O</kbd>), or — if Motrix is your default torrent handler — just double-click any `.torrent` file in your file manager.

### 4.3 Download from a Magnet link

Magnet links are handled on the **URL** tab — just paste the `magnet:?xt=...` link like any other URL. If you have enabled magnet-link capture (see [Preferences ▸ Protocols](#74-protocols)), clicking a magnet link in your browser opens it directly in Motrix.

> [!WARNING]
> **Thunder links** (`thunder://`) are accepted but may not be downloadable after decoding. Motrix shows the tip *"Thunder links may not be downloadable after decoding"* when it detects one. Thunder protocol handling is **off by default**.

---

## 5. Managing Tasks

Right-click any task (or use its row actions and the **Task** menu) to control it.

### 5.1 Per-task actions

| Action | Label | Notes |
|--------|-------|-------|
| Pause | **Pause Task** | Stops transfer; resumable later. For BT tasks Motrix uses a *force* pause |
| Resume | **Resume Task** | Continues a paused/waiting task |
| Delete | **Delete Task** | Removes the active/waiting task. Optionally **Delete with Files** |
| Show in folder | **Show Task In Folder** | Opens your file manager at the downloaded file |
| Copy link | **Copy Link** | Copies the task's source URL to the clipboard |
| Move up / down | **Move Task Up / Down** | Reorders queued tasks |
| Remove record | **Remove Task Record** | For finished/errored tasks: removes the history entry (optionally with files) |

> [!CAUTION]
> **Delete with Files** permanently deletes the downloaded data from disk, not just the task entry. By default Motrix asks for confirmation before deleting a task — you can disable that prompt in Preferences (*"No confirmation is required before deleting task"*), so be careful if you turn it off.

### 5.2 Bulk and global actions

| Action | Label | Shortcut |
|--------|-------|----------|
| Select all | **Select All Tasks** | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>A</kbd> |
| Pause all | **Pause All Tasks** | <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> |
| Resume all | **Resume All Tasks** | <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd> |
| Delete selected | **Delete Selected Tasks** | — |
| Purge records | **Purge Task Record** | Clears all finished/errored history at once |
| Clear recent | **Clear Recent Tasks** | Clears the OS "recent documents" list |

You can also select multiple tasks (drag-select or <kbd>Ctrl</kbd>-click) and then pause, resume, or delete them in a single batch.

### 5.3 Task status colors

Each task shows a status color that maps to its state:

| Status | Meaning | Color |
|--------|---------|-------|
| `active` | Downloading | `#5b5bea` (blue) |
| `waiting` | Queued | `#737373` (grey) |
| `paused` | Paused | `#737373` (grey) |
| `complete` | Finished | `#2ACB42` (green) |
| `seeding` | Seeding (BT) | `#2ACB42` (green) |
| `error` | Failed | `#FF6157` (red) |
| `removed` | Removed | `#737373` (grey) |

### 5.4 Completion notifications

When **Notify after download is complete** is enabled, Motrix shows a desktop notification — *"Download Completed"* — and adds the file to your OS recent-documents list. For torrents you'll see *"BT Download Completed, seeding…"* with the tip that you can stop the task to end seeding.

---

## 6. BitTorrent & Magnet Downloads

Motrix is a capable BitTorrent client, not just an HTTP downloader. It supports selective file download, peer exchange, DHT, Local Peer Discovery, and an automatically-updated tracker list.

### 6.1 Selective download

When you add a torrent, Motrix shows every file inside it. **Untick files you don't want** before submitting. Motrix is configured to remove unselected files when the download completes, so you only keep what you asked for.

### 6.2 Seeding

After a torrent finishes, Motrix continues **seeding** (uploading to other peers) according to your seed settings:

- **Seed Ratio** — stop seeding once you've uploaded this multiple of the download size (default **2**).
- **Seed Time** — stop seeding after this many minutes (default **2880** minutes = 48 hours).
- **Keep seeding until manually stopped** — overrides the limits and seeds indefinitely.

To end seeding for a task immediately, **stop** it. Motrix shows *"Stopping seeding, it will take some time to disconnect, please wait patiently."*

> [!TIP]
> Seeding is good etiquette — it keeps torrents healthy for everyone. But if you're tight on bandwidth, set a modest **Seed Ratio** (e.g. `1`) or short **Seed Time** so Motrix releases the task once you've given a fair share back.

### 6.3 Trackers

Trackers help your client find peers. Motrix can **update its tracker list automatically every day** from community-maintained sources ([ngosang/trackerslist](https://github.com/ngosang/trackerslist) and [XIU2/TrackersListCollection](https://github.com/XIU2/TrackersListCollection)). Enable this with *"Update tracker list every day automatically"* in Preferences, or click **Sync** to update on demand. You can also paste your own tracker servers (one per line).

### 6.4 Saving magnet metadata

Enable **Save magnet link as torrent file** to have Motrix write a `.torrent` file once it fetches a magnet link's metadata, so you can reuse it later without re-resolving the magnet.

---

## 7. Preferences

Open Preferences with <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>,</kbd> or the **Motrix ▸ Preferences** menu. Settings are grouped into three tabs: **Basic**, **Advanced**, and **Lab**. After changing anything, click **Save & Apply** (you'll see *"Preferences saved successfully"*).

> [!IMPORTANT]
> Some settings require the engine to restart to take effect: **BT Listen Port**, **DHT Listen Port**, **RPC Listen Port**, **RPC Secret**, and **Hide App Menu**. Motrix handles the restart for you when you save.

### 7.1 Basic settings

**Startup**
- **Open at login** — launch Motrix when you sign in.
- **Keep size and position of the window when exited** — restore your window layout next launch.
- **Automatically resume all unfinished tasks** — pick up where you left off after a restart.
- **Default Path** — where downloads are saved by default.

**Transmission (speed)**
- **Upload limit** / **Download limit** — cap transfer speed, or leave **Unlimited**.

**BitTorrent**
- **Save magnet link as torrent file**, **Automatically download magnet and torrent content**, **BT force encryption**, **Keep seeding until manually stopped**, **Seed Ratio**, **Seed Time**.

**Task Management**
- **Maximum active tasks** — how many downloads run at once (default **5**; the engine supports up to **10**).
- **Maximum connections per server** — parallel connections per task (default **64**).
- **Automatically show downloading after adding task**.
- **No confirmation is required before deleting task**.
- **Notify after download is complete**.
- **Automatically purge download records when exiting app**.

**UI (Appearance)**
- **Theme** — **Auto**, **Light**, or **Dark**.
- **Auto Hide Window**.
- **Run As** — **Standard Application**, **Tray Application**, or **Hide Tray Application** (see [Run modes](#102-run-modes)).
- **Show the real-time speed in the menu bar tray** *(macOS)*.
- **Show download progress bar**.
- **Language** — Motrix is translated into 25 languages.
- **Hide App Menu (Windows & Linux Only)**.

### 7.2 Advanced settings

- **Proxy** — enable a proxy and choose its **scope**: **Download**, **Update Application**, and/or **Update Trackers**. Add hosts/domains to bypass (one per line).
- **Tracker Servers** — paste tracker URLs (one per line) and toggle daily auto-sync.
- **Listen Ports** — **BT Listen Port** (default `21301`) and **DHT Listen Port** (default `26701`).
- **Security ▸ RPC** — **RPC Listen Port** (default `16800`) and **RPC Secret** (see warning below).
- **Developer** — **Mock User-Agent** (impersonate a browser or another client), plus read-only paths for the built-in `aria2.conf`, app log, and download session.

> [!CAUTION]
> **Set an RPC Secret.** Motrix's bundled engine exposes a local control port (RPC) so the app can drive downloads. By default this has **no secret**. If you run Motrix on a shared or untrusted network, set an **RPC Secret** in Preferences to prevent other processes from issuing commands to your download engine. See the Admin Guide's Security section for the full picture.

### 7.3 Lab settings

Experimental features live under the **Lab** tab, behind an explicit warning: *"⚠️ Enabling lab features may result in app crash or data loss, decide at your own risk!"* Two reset actions also live here:

- **Reset download session** — clears the engine's saved session (*"Are you sure you want to reset download session?"*).
- **Factory Reset** — reverts **all** preferences to defaults and relaunches (*"Are you sure you want to revert to factory settings?"*).

### 7.4 Protocols

Under **Protocols**, choose which link types Motrix registers itself as the default handler for:

- **Magnet** (`magnet://`) — **on by default**.
- **Thunder** (`thunder://`) — **off by default**.

With magnet capture enabled, clicking a magnet link in your browser opens it straight in Motrix.

---

## 8. Common Tasks (Recipes)

**Download a batch of files at once**
: Open New Task, paste all the links (one per line), set **Save to**, **Submit**. Motrix queues them and runs up to your *Maximum active tasks* limit concurrently.

**Speed up a slow single-file download**
: Open the task, or before adding raise **Splits** toward 64. More connections = more parallel byte-range requests to the same server.

**Cap your bandwidth during work hours**
: Preferences ▸ Basic ▸ **Transmission** ▸ set **Download limit** / **Upload limit**. Set back to **Unlimited** afterward.

**Download behind a login**
: In New Task ▸ **Advanced Options**, paste the required **Cookie** (and **Referer**/**Authorization** if needed). Motrix sends them with the request.

**Keep downloads running after reboot**
: Preferences ▸ Basic ▸ Startup ▸ enable **Open at login** and **Automatically resume all unfinished tasks**.

**Run Motrix purely from the tray**
: Preferences ▸ UI ▸ **Run As** ▸ **Tray Application** (or **Hide Tray Application**). The main window stays hidden until you click the tray icon.

**Use a proxy only for app updates, not downloads**
: Preferences ▸ Advanced ▸ **Proxy** ▸ enable, set the server, and tick only **Update Application** in the scope.

**Free up disk after a torrent finishes**
: Right-click the finished task ▸ **Remove Task Record** ▸ tick **Delete with Files**.

---

## 9. Keyboard Shortcuts

Motrix's built-in shortcuts (the `cmdctrl` prefix means <kbd>Cmd</kbd> on macOS, <kbd>Ctrl</kbd> on Windows/Linux):

| Shortcut | Action |
|----------|--------|
| <kbd>Ctrl/Cmd</kbd> + <kbd>N</kbd> | New Task |
| <kbd>Ctrl/Cmd</kbd> + <kbd>Shift</kbd> + <kbd>N</kbd> | New BT Task |
| <kbd>Ctrl/Cmd</kbd> + <kbd>O</kbd> | Open Torrent File… |
| <kbd>Ctrl/Cmd</kbd> + <kbd>L</kbd> | Go to Task List |
| <kbd>Ctrl/Cmd</kbd> + <kbd>,</kbd> | Preferences |
| <kbd>Ctrl/Cmd</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> | Pause All Tasks |
| <kbd>Ctrl/Cmd</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd> | Resume All Tasks |
| <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>A</kbd> | Select All Tasks |
| <kbd>Ctrl/Cmd</kbd> + <kbd>Enter</kbd> | Submit the New Task dialog |
| <kbd>Ctrl/Cmd</kbd> + <kbd>Q</kbd> | Quit Motrix |

> [!TIP]
> On the Snap build of Motrix, the tray indicator may not display correctly, making it hard to quit from the tray. Use <kbd>Ctrl</kbd> + <kbd>Q</kbd> to exit cleanly.

---

## 10. How Motrix Works (Concepts)

You don't need this section to use Motrix, but it explains *why* it behaves the way it does.

### 10.1 The aria2 engine

Motrix is a friendly interface on top of **aria2**, a powerful command-line download utility. When Motrix starts, it launches its own private copy of aria2 as a background process and talks to it over a local control channel. aria2 does the actual downloading — connecting to servers and peers, splitting files, retrying, seeding — while Motrix shows you progress and sends it your commands. This is why Motrix can do things like 64-connection splits and full BitTorrent: those are aria2 capabilities, exposed through a clean UI.

> [!NOTE]
> Motrix maintains **two layers of settings**: your *app preferences* (theme, language, window behavior) and the *engine options* (connections, ports, seeding, BitTorrent tuning) that are passed to aria2. Most of what you set in Preferences ▸ Advanced are engine options. The complete engine option reference is in the Admin Guide.

### 10.2 Run modes

**Run As** controls how Motrix presents itself:

| Mode | Behavior |
|------|----------|
| **Standard Application** | Normal app — dock/taskbar icon and tray icon |
| **Tray Application** | Lives in the tray; no dock icon. Click the tray to show/hide |
| **Hide Tray Application** | Runs with no tray indicator |

### 10.3 Where your data lives

Your settings, download history, and session are stored in Motrix's per-user data folder (the exact location is OS-specific; the Admin Guide lists the paths). The **portable** Windows build instead keeps everything next to the executable, so you can carry it on a USB drive.

> [!NOTE]
> The portable build still resolves some OS paths from the host; if you need Motrix to keep *everything* in the portable folder, verify the data location on a fresh machine before relying on it for sensitive data (see GitHub issue #1016).

---

## 11. Troubleshooting

Motrix shows precise messages. Find yours below.

### Error: The download engine failed to start

**Symptom:** A system-error dialog appears on launch, or no downloads will start.
**Cause:** Motrix could not find or launch the bundled aria2 binary (internal message: *engine bin is not exist*).
**Solution:** Reinstall Motrix from the official installer so the bundled `engine/` folder is restored intact. On Linux, run Motrix once with `sudo` so it can create its session file.
**Prevention:** Don't move or delete files inside the Motrix application folder, and don't block the bundled `aria2c` in your antivirus/firewall.

### Error: White screen on launch

**Symptom:** The window opens blank/white (GitHub #1502, #1728).
**Cause:** A rendering/GPU issue on some systems.
**Solution:** Quit fully (<kbd>Ctrl</kbd> + <kbd>Q</kbd> or via the tray) and relaunch. If it persists, update your graphics drivers, or try the latest Motrix release where rendering fixes may apply.
**Prevention:** Keep Motrix and your GPU drivers up to date.

### Error: Download fails with "error #22"

**Symptom:** A task fails and the engine reports error 22 (GitHub #452, #1787).
**Cause:** aria2 error code 22 means the **HTTP server returned an unexpected/error response header** (for example, the URL now serves an HTML error page rather than the file).
**Solution:** Open the link in a browser to confirm it still serves the file directly. If it redirects to a login or landing page, supply the needed **Cookie**/**Referer** in Advanced Options, or get a fresh direct link.
**Prevention:** Use direct file links rather than share-page URLs.

### Error: A download returns an HTML page instead of the file

**Symptom:** The "downloaded" file is actually an `index.html` (GitHub #1801).
**Cause:** The server requires session/referrer headers and served its web page instead of the file.
**Solution:** Add the required **Cookie**, **Referer**, or **User-Agent** in the New Task **Advanced Options**.
**Prevention:** Capture the link from the network panel of your browser after authenticating.

### Error: Magnet stuck at 0%

**Symptom:** A magnet that downloads elsewhere stays at 0% in Motrix (GitHub #1767).
**Cause:** No peers are being found — usually a tracker/DHT reachability problem.
**Solution:** Enable **Update tracker list every day automatically** (or click **Sync**), make sure **DHT** and your **BT/DHT Listen Ports** aren't blocked by a firewall, and enable **UPnP** so your router opens the ports.
**Prevention:** Keep the tracker list fresh and allow Motrix through your firewall.

### Error: "Failed to delete task file(s), please delete them manually"

**Symptom:** Deleting a task with files leaves the files behind.
**Cause:** The files are locked or Motrix lacks permission to remove them.
**Solution:** Close any program using the file and delete it manually from the folder shown by **Show Task In Folder**.
**Prevention:** Don't open downloaded media in another app while deleting its task.

### Tray speed meter always/never shows (or tray text issues)

**Symptom:** The tray speedometer ignores its toggle (GitHub #1768), or the Snap tray font/dialog renders incorrectly (#1786).
**Cause:** Known platform-specific tray rendering quirks.
**Solution:** Toggle **Show the real-time speed in the menu bar tray** off/on and **Save & Apply**. On Snap, exit via <kbd>Ctrl</kbd> + <kbd>Q</kbd> and update to the latest version.

### `yarn dev` fails with "Cannot find module … DescriptionDataMatcherRulePlugin"

**Symptom:** Building from source fails (GitHub #1070).
**Cause:** A stale or mismatched `node_modules`.
**Solution:** Delete `node_modules` and reinstall (`yarn`). If Electron itself fails to install, see the Electron install note in the project README.
**Prevention:** Use the Node version Motrix targets (Node ≥ 16).

---

## 12. FAQ

**Q: Is Motrix free? Does it cost anything?**
Yes, it's completely free and open source under the MIT license. There are no paid tiers.

**Q: Do I need to install aria2 separately?**
No. Motrix bundles its own aria2 engine. Installing aria2 system-wide is neither required nor used by Motrix.

**Q: What can Motrix download?**
HTTP, HTTPS, FTP, BitTorrent (`.torrent` files), and Magnet links. Thunder (`thunder://`) links are accepted but may not decode to a usable download.

**Q: Does Motrix support ed2k / eMule links?**
No. ed2k is not supported (GitHub #553). Motrix's engine handles HTTP/FTP/BitTorrent/Metalink only.

**Q: How many downloads can run at once?**
Up to your **Maximum active tasks** setting (default 5; the engine allows up to 10). Each task can use up to **Maximum connections per server** connections (default 64).

**Q: How do I make a download faster?**
Increase **Splits** for that task and make sure **Maximum connections per server** is high. Speed is ultimately limited by the source server and your connection.

**Q: Why does my torrent keep uploading after it finished?**
That's **seeding**. Motrix seeds until it hits your **Seed Ratio** (default 2) or **Seed Time** (default 48h), unless you enabled *Keep seeding until manually stopped*. Stop the task to end seeding now.

**Q: Can I change where files are saved?**
Yes — set **Default Path** in Preferences, or **Save to** per task. Motrix remembers recent and favorite directories.

**Q: Is there a dark mode?**
Yes. Preferences ▸ UI ▸ **Theme** ▸ **Dark** (or **Auto** to follow your system).

**Q: How do I run Motrix in the background only?**
Set **Run As** to **Tray Application** or **Hide Tray Application**, and optionally enable **Auto Hide Window**.

**Q: Can other apps control Motrix's downloads?**
Motrix exposes a local aria2 RPC port for its own use. Anything that can reach that port and knows the secret can issue commands. Set an **RPC Secret** if you're concerned (see the caution in Preferences ▸ Advanced).

**Q: Is Motrix still maintained?**
Development has slowed (GitHub #1396, #1807). The app remains fully usable; this guide documents version 1.8.19.

**Q: There's a paid "Motrix" in an app store / a "proxy download" site using the name — are those official?**
Be cautious. The community has flagged a paid look-alike (#1810) and an abusive "proxy download" service using the Motrix name (#1792). The official app is free and distributed from [GitHub Releases](https://github.com/agalwood/Motrix/releases) and [motrix.app](https://motrix.app).

**Q: How do I completely reset Motrix?**
Preferences ▸ **Lab** ▸ **Factory Reset**. This reverts all settings and relaunches. To clear just the engine state, use **Reset download session**.

---

## 13. Reference

### 13.1 Supported protocols

| Protocol | Example | Default handler |
|----------|---------|-----------------|
| HTTP/HTTPS | `https://example.com/file.zip` | — |
| FTP | `ftp://example.com/file.zip` | — |
| Magnet | `magnet:?xt=urn:btih:…` | On |
| BitTorrent | `.torrent` file | On (file association) |
| Thunder | `thunder://…` | Off |
| Motrix | `mo://` / `motrix://` | On (internal app links) |

### 13.2 Key defaults

| Setting | Default |
|---------|---------|
| Maximum active tasks | 5 (engine cap 10) |
| Maximum connections per server | 64 |
| Seed Ratio | 2 |
| Seed Time | 2880 minutes (48 hours) |
| BT Listen Port | 21301 |
| DHT Listen Port | 26701 |
| RPC Listen Port | 16800 |
| RPC Secret | *(empty — set one for security)* |
| Theme | Auto |
| Magnet capture | On |
| Thunder capture | Off |
| UPnP/NAT-PMP | On |
| Auto-update | On (macOS by default) |

### 13.3 Supported languages

Arabic, Bulgarian, Catalan, German, Greek, English, Spanish, Persian, French, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian Bokmål, Dutch, Polish, Portuguese (Brazil), Romanian, Russian, Thai, Turkish, Ukrainian, Vietnamese, Simplified Chinese, and Traditional Chinese.

### 13.4 Where to go next

- **Official site & manual:** [motrix.app](https://motrix.app) · [Wiki](https://github.com/agalwood/Motrix/wiki)
- **Report a problem:** [motrix.app/report](https://motrix.app/report)
- **Architecture, full engine option reference, security & deployment:** the Motrix **Admin Guide**

---

_Generated June 2026 from agalwood/Motrix at 7012040. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._