# How BitTorrent Downloads Work in Motrix: Magnet Links, Metadata, and Tracker Management > Discover how Motrix handles BitTorrent downloads. Learn about magnet link resolution, metadata acquisition, and dynamic tracker management for efficient file sharing. - Repository: [Dr_rOot/Motrix](https://github.com/agalwood/Motrix) - Tags: deep-dive - Published: 2026-08-19 --- **Motrix processes BitTorrent downloads through a specialized pipeline where magnet links first enter a metadata-only resolution phase, convert into full torrent tasks after user file selection, and download using dynamically managed tracker lists.** Motrix, the open-source download manager developed at agalwood/Motrix, implements BitTorrent functionality through a coordinated system of task managers, magnet trackers, and tracker synchronizers. Understanding how BitTorrent downloads function in Motrix requires examining how the application handles the transition from magnet URI to active download, including the critical metadata resolution and tracker injection stages. ## Submitting Magnet Links and Initializing Tasks When you add a magnet link to Motrix, the renderer process sends an IPC command (`Commands.CreateTask`) to the server layer defined in [`src/server/ipc/commands.ts`](https://github.com/agalwood/Motrix/blob/main/src/server/ipc/commands.ts). The server detects the `magnet:?` prefix and routes the request to `MagnetTracker.submit()` in [`src/core/torrent/magnet-tracker.ts`](https://github.com/agalwood/Motrix/blob/main/src/core/torrent/magnet-tracker.ts) rather than treating it as a standard HTTP download. ### The Metadata-Only Fetch Phase If the user has enabled `magnetFileSelection` in preferences, Motrix initiates a **shielded metadata fetch** rather than starting the download immediately. According to the source code in [`magnet-tracker.ts`](https://github.com/agalwood/Motrix/blob/main/magnet-tracker.ts) (lines 30-50), the process executes the following steps: 1. **Reserve a GID**: Motrix calls `reserveNewEngineGid()` to allocate a unique identifier that shields the task from the main download list while fetching metadata. 2. **Create temporary storage**: The system generates a temporary directory via `mkdtemp()` to store the incoming `.torrent` file. 3. **Persist task row**: A new `TaskRow` is created with `kind: Bt` and `taskType: Magnet`, indicating this is a BitTorrent task in the metadata resolution phase. 4. **Dispatch to aria2**: The magnet URI is submitted to the aria2 engine with the `bt-metadata-only: true` flag set, ensuring only the torrent structure is retrieved, not the content. The `MetadataInstanceCache` stores this pending operation in an in-memory map keyed by the reserved GID, enabling polling and timeout monitoring via the `observe()` method. ## Resolving Metadata and Swapping to Full Downloads Once aria2 completes the metadata fetch, `MagnetTracker.onComplete()` triggers. This method parses the saved torrent metadata using `TorrentParser` and emits `Events.MagnetFileSelection`, signaling the UI to present a file-selection dialog. This allows users to deselect unwanted files before the actual content download begins. ### The Swap Process from Metadata to BT Task When the user confirms their file selection, Motrix executes `swapMagnetMetadataForBt()` from [`src/core/torrent/swap-magnet-metadata-for-bt.ts`](https://github.com/agalwood/Motrix/blob/main/src/core/torrent/swap-magnet-metadata-for-bt.ts) to transition the task state: - **Cancel metadata task**: `MagnetTracker.cancel()` removes the temporary aria2 GID and cleans up the metadata-only reservation. - **Add full torrent**: `Aria2RpcClient.addTorrent()` receives the parsed torrent bytes and the user-selected file list, creating the actual download task. - **Preserve identity**: The original Motrix task ID persists through the swap, ensuring the UI seamlessly transitions from "Fetching Metadata" to "Downloading" without creating duplicate entries. ## Global and Per-Task Tracker Management Motrix maintains tracker functionality through two distinct mechanisms: global tracker list synchronization and per-task tracker injection. ### Synchronizing Global Tracker Lists The `TrackerSyncer` class in [`src/core/tracker/tracker-syncer.ts`](https://github.com/agalwood/Motrix/blob/main/src/core/tracker/tracker-syncer.ts) periodically fetches public tracker lists from remote sources such as `https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_best.txt`. The synchronizer validates tracker schemes (accepting only `udp`, `http`, or `https`), deduplicates entries, and maintains a clean global array available for all new BT tasks. ### Attaching Trackers to Individual Tasks For specific downloads, `TrackerManager.setBtTrackerOwned()` in [`src/core/tracker/tracker-manager.ts`](https://github.com/agalwood/Motrix/blob/main/src/core/tracker/tracker-manager.ts) handles tracker assignment. When called, this method updates the aria2 RPC call with the `bt-tracker` parameter, injecting the specified tracker URLs into the active download session. The renderer process provides a utility for constructing magnet URIs with embedded trackers. The `buildMagnetUri()` function in [`src/renderer/lib/magnet.ts`](https://github.com/agalwood/Motrix/blob/main/src/renderer/lib/magnet.ts) appends URL-encoded `tr=` parameters to magnet links, automatically filtering duplicates and empty strings (verified in [`src/renderer/lib/magnet.test.ts`](https://github.com/agalwood/Motrix/blob/main/src/renderer/lib/magnet.test.ts)). ## Error Handling and Cleanup Mechanisms Motrix implements robust failure recovery to handle stalled metadata fetches or RPC communication errors. ### Quarantine and Retry Logic If aria2 cannot remove a GID due to temporary RPC failure, the cache entry is marked as `quarantined`. A retry timer executes cleanup attempts at escalating intervals (5s, 10s, 20s, continuing up to 6 attempts) via `cleanupCacheEntry()`. For timeout scenarios, `MagnetTracker.handleTimeout()` or `MagnetTracker.onError()` (lines 626-660 in [`magnet-tracker.ts`](https://github.com/agalwood/Motrix/blob/main/magnet-tracker.ts)) mark the task as `Error` and release the reservation. ### Atomic State Persistence All database updates occur within `runTaskMutation()` or `runExclusivePersistence()` callbacks, ensuring atomicity between the persisted state, the in-memory `TaskManager`, and UI notifications. When users cancel a metadata task, the database row persists as a hidden tombstone, allowing Motrix to reconstruct the shielded GID state after application restarts. ## Summary - **Magnet links enter a metadata-only phase** controlled by `MagnetTracker.submit()`, which reserves a GID and fetches only the `.torrent` structure before showing file selection. - **File selection triggers a task swap** via `swapMagnetMetadataForBt()`, canceling the metadata fetch and creating the real BT download while preserving the original Motrix task ID. - **Trackers are managed globally** through `TrackerSyncer` fetching remote lists, and per-task via `TrackerManager.setBtTrackerOwned()`, which injects trackers into the aria2 `bt-tracker` parameter. - **Renderer utilities** like `buildMagnetUri()` ensure proper magnet link formatting with URL-encoded tracker parameters. - **Failure recovery** uses quarantine logic with exponential backoff retries and atomic database transactions to prevent state corruption. ## Frequently Asked Questions ### How does Motrix handle magnet links differently from torrent files? Motrix routes magnet links through a dedicated metadata resolution pipeline before starting the actual download. While `.torrent` files can start immediately via `addTorrent`, magnet URIs are first submitted with `bt-metadata-only: true` to retrieve the torrent structure, enabling the file-selection dialog that torrent files provide natively. ### What happens if metadata fetching fails or times out? If the metadata fetch exceeds the timeout threshold or encounters an error, `MagnetTracker.handleTimeout()` or `onError()` marks the task status as `Error`, cleans up the temporary directory, and releases the reserved GID. The UI receives this status change and displays the failure to the user without leaving orphaned processes. ### How does Motrix manage and update tracker lists for BitTorrent tasks? The `TrackerSyncer` periodically downloads and validates public tracker lists from configured URLs, storing them for global use. When a BT task starts, `TrackerManager` can append these global trackers or accept custom trackers from the user, applying them via the aria2 `bt-tracker` RPC parameter to maximize peer discovery. ### Can users customize trackers for individual downloads? Yes, users can edit the tracker list for any active BitTorrent task through the UI. These changes route to `TrackerManager.setBtTrackerOwned()`, which updates the running aria2 process with the new tracker configuration. The renderer also supports building custom magnet URIs with specific trackers using the `buildMagnetUri()` helper function.