# How to Build Motrix from Source: Complete Development Guide

> Learn to build Motrix from source using Node.js 22+ and pnpm. Follow our three-step guide for dependency installation, Vite compilation, and native-host packaging to create cross-platform Electron binaries.

- Repository: [Dr_rOot/Motrix](https://github.com/agalwood/Motrix)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Motrix requires Node.js 22+ and pnpm to build from source, using a three-step workflow of dependency installation, Vite compilation for four process targets, and native-host packaging to produce cross-platform Electron binaries.**

Motrix is a modern download manager built on Electron, React, and TypeScript. Building Motrix from source allows you to customize the aria2 download engine, modify the React-based user interface, or contribute to the core Electron application. This guide walks through the exact build process as defined in the `agalwood/Motrix` repository, including the specific Vite configurations and native compilation steps required to reproduce the official binaries.

## Prerequisites for Building Motrix

Before compiling, ensure your environment meets the requirements specified in [`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json) at the repository root.

- **Node.js 22+**: The build system requires modern Node.js features for the Vite-based pipeline.
- **pnpm**: The project uses pnpm as its package manager, with the exact version declared in [`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json).
- **Platform tools**: The build script automatically downloads the correct aria2 binary for your operating system and compiles the native-host wrapper without manual intervention.

## Step-by-Step Build Process

Building Motrix follows a streamlined three-step workflow orchestrated through npm scripts.

### 1. Clone the Repository

Start by cloning the official source:

```bash
git clone https://github.com/agalwood/Motrix.git
cd Motrix

```

### 2. Install Dependencies

Run `pnpm install` to resolve all npm packages, pull the pre-built aria2 binary, and rebuild any native modules:

```bash
pnpm install

```

This command automatically handles the platform-specific aria2 engine download and prepares the native-host wrapper for compilation as defined in the repository's dependency tree.

### 3. Compile the Application

Execute `pnpm build` to trigger the full compilation sequence:

```bash
pnpm build

```

This command runs Vite builds for the main process, preload script, worker, and renderer, then packages the native-host via `packages/native-host/build.mjs`. Final artifacts are placed in the `dist` folder.

## Development and Testing Workflow

After building, you can run the application in development mode or execute the test suite to verify functionality.

### Run the Development Build

Launch Electron with hot-module reload using:

```bash
pnpm start

```

### Execute Tests

Verify your build with the included test suites:

```bash
pnpm test       # Unit tests via Vitest

pnpm test:e2e   # End-to-end tests via Playwright

```

## Key Build Configuration Files

Understanding these core files helps troubleshoot build issues or customize the compilation process.

**[`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json)**: Defines the pnpm version, Node.js engine requirements, and build scripts. It also declares dependencies for the aria2 fork used by the download engine.

**[`vite.main.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.main.config.ts)**: Orchestrates bundling of the Electron main process and integrates the native-host build into the pipeline.

**[`vite.renderer.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.renderer.config.ts)**: Configures the Vite build for the React-based UI bundle loaded by the Electron window.

**[`vite.preload.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.preload.config.ts)**: Compiles the preload script that exposes the `window.motrix` IPC bridge between main and renderer processes.

**`packages/native-host/build.mjs`**: The native-host build script that compiles the wrapper around the bundled aria2 engine and handles platform-specific packaging tasks.

**[`electron-builder.json`](https://github.com/agalwood/Motrix/blob/main/electron-builder.json)**: Defines platform-specific installers (`.dmg`, `.exe`, `.AppImage`) and packaging rules for distribution.

## Building the Native Host Manually

If you need to customize the native wrapper for the aria2 engine rather than using the auto-compiled version, build it separately:

```bash
cd packages/native-host
pnpm run build

```

This invokes `packages/native-host/build.mjs` directly, allowing modifications to how the native host interacts with the aria2 binary before repackaging the full application.

## Summary

- **Requirements**: Node.js 22+ and pnpm are mandatory; the build system auto-downloads platform-specific aria2 binaries during installation.
- **Core workflow**: Run `pnpm install` followed by `pnpm build` to generate production-ready binaries in the `dist` folder.
- **Architecture**: The build compiles four Vite targets (main, preload, worker, renderer) plus the native-host wrapper that manages the aria2 engine.
- **Customization**: Modify `packages/native-host/build.mjs` to change native-host behavior, or edit the Vite configs to adjust bundling settings for specific platforms.

## Frequently Asked Questions

### What version of Node.js is required to build Motrix?

Motrix requires Node.js 22 or higher, as specified in the engine requirements within [`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json). The build pipeline uses modern Node.js features for the Vite-based compilation system that bundles the Electron main process and React renderer.

### Does building from source require manual installation of aria2?

No. Running `pnpm install` automatically downloads the correct pre-built aria2 binary for your platform and compiles the native-host wrapper. Manual intervention is only needed if you specifically want to modify the native-host source code in `packages/native-host/` before running the build.

### How do I create distributable installers after building?

Once `pnpm build` completes and outputs files to the `dist` folder, you can generate platform-specific installers using Electron-Builder. The configuration in [`electron-builder.json`](https://github.com/agalwood/Motrix/blob/main/electron-builder.json) defines targets for `.dmg` (macOS), `.exe` (Windows), and `.AppImage` (Linux).

### Can I run Motrix in development mode without building the full application?

Yes. Use `pnpm start` to launch Electron with hot-module reloading enabled. This command skips the full packaging step defined in [`electron-builder.json`](https://github.com/agalwood/Motrix/blob/main/electron-builder.json) and is useful for iterative UI development and testing changes to the React renderer without generating final binaries.