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 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.

Table of Contents

1. Quick Start
2. Installation
3. The Motrix Window at a Glance
4. Adding Downloads
5. Managing Tasks
6. BitTorrent & Magnet Downloads
7. Preferences
8. Common Tasks (Recipes)
9. Keyboard Shortcuts
10. How Motrix Works (Concepts)
11. Troubleshooting
12. FAQ
13. Reference

1. Quick Start

Get your first download running in under a minute.

1. Install Motrix for your operating system (see Installation).
2. Launch Motrix. The main window opens on the Downloading task list.
3. Add a download. Press Ctrl/Cmd + N (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 Ctrl/Cmd + Enter).

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 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:

# 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:

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:

# 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 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.

3. The Motrix Window at a Glance

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

Switch between lists from the sidebar or with Ctrl/Cmd + L. 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 Ctrl/Cmd + N. 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.

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:

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… (Ctrl/Cmd + O), 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), 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

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

You can also select multiple tasks (drag-select or Ctrl-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:

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 and 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 Ctrl/Cmd + , 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).
• 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 Cmd on macOS, Ctrl on Windows/Linux):

Tip

On the Snap build of Motrix, the tray indicator may not display correctly, making it hard to quit from the tray. Use Ctrl + Q 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:

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 (Ctrl + Q 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 Ctrl + Q 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 and 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

13.2 Key defaults

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 · Wiki
• Report a problem: motrix.app/report
• Architecture, full engine option reference, security & deployment: the Motrix Admin Guide