How to Build escrcpy for Different Platforms: Windows, macOS, and Linux Guide

To build escrcpy for Windows, macOS, or Linux, install Node.js 18+, enable Corepack, run pnpm install, then execute pnpm build for auto-detection or use pnpm build:win, pnpm build:mac, or pnpm build:linux for specific targets.

escrcpy is a multi-platform Electron application organized as a pnpm + TurboRepo monorepo. The build pipeline uses platform-specific orchestration scripts located in desktop/build/ to invoke electron-builder with the correct configuration for each operating system.

Prerequisites for Building escrcpy

Before compiling the application, ensure your environment meets the baseline requirements. The repository uses pnpm as its package manager and requires Node.js 18 or higher.

Enable Corepack to manage pnpm automatically, then install all workspace dependencies:

corepack enable pnpm
pnpm install

This command installs packages across all workspaces (desktop, wscrcpy, madb, etc.) and initializes the Turbo build cache.

Understanding the Build Architecture

The build system relies on three core components working in sequence. First, TurboRepo coordinates tasks across the monorepo packages. Second, Vite bundles the Electron renderer processes (main, control, explorer interfaces) using the configuration in desktop/vite.config.js. Third, electron-builder packages the compiled assets into native installers.

The repository defines explicit build commands in the root package.json. Each command invokes a platform-specific script—desktop/build/platform-win.js, desktop/build/platform-mac.js, or desktop/build/platform-linux.js—that sets the appropriate TARGET_PLATFORM environment variable and orchestrates electron-builder using desktop/electron-builder.config.js.

Building for Specific Platforms

Auto-Detecting the Host Platform

Running the generic build command allows Turbo to detect your current operating system and invoke the corresponding platform script automatically:

pnpm build

Under the hood, this executes the platform script matching your OS, rebuilds native Node.js modules via desktop/build/native-modules.js, and outputs distributables to desktop/dist/.

Targeting Windows Explicitly

To force a Windows build regardless of your host OS, use the dedicated Windows script. This is essential for CI pipelines or cross-compilation environments:

pnpm build:win

The script desktop/build/platform-win.js configures electron-builder with Windows-specific targets (.exe, .msi, .zip) and handles any Windows-specific signing or metadata configuration defined in desktop/electron-builder.config.js.

Targeting macOS Explicitly

For macOS distribution, execute the mac-specific build command:

pnpm build:mac

This invokes desktop/build/platform-mac.js, which targets macOS formats (.dmg, .pkg) and ensures native modules are rebuilt against the correct Electron ABI for Darwin systems.

Targeting Linux Explicitly

To generate Linux installers and portable packages, run:

pnpm build:linux

The desktop/build/platform-linux.js script configures targets such as AppImage, DEB, and RPM. The output appears in desktop/dist/ as escrcpy-<version>-linux-x64.AppImage or equivalent package formats.

Key Build Scripts and Configuration Files

The following files define the complete build pipeline referenced above:

• desktop/build/platform-win.js – Orchestrates electron-builder for Windows targets (source)
• desktop/build/platform-mac.js – Orchestrates electron-builder for macOS targets (source)
• desktop/build/platform-linux.js – Orchestrates electron-builder for Linux targets (source)
• desktop/electron-builder.config.js – Central configuration for artifact naming, signing, and target formats (source)
• desktop/vite.config.js – Vite configuration bundling the renderer entries (source)
• develop.md – High-level developer documentation outlining build workflows (source)
• package.json – Root manifest defining the build, build:win, build:mac, and build:linux scripts (source)

Build Output and Artifacts

After a successful compilation, packaged binaries and installers appear in the desktop/dist/ directory. The specific files depend on your target platform:

• Windows: escrcpy-<version>-win-x64.exe, .msi, or .zip
• macOS: escrcpy-<version>-mac-x64.dmg or .pkg
• Linux: escrcpy-<version>-linux-x64.AppImage, .deb, or .rpm

These artifacts are ready for direct distribution, GitHub releases, or submission to package managers like Homebrew or Chocolatey.

Summary

• Install prerequisites: Node.js 18+, Corepack, and pnpm via corepack enable pnpm
• Install dependencies: Run pnpm install from the repository root
• Build automatically: Use pnpm build to detect the host OS and package accordingly
• Target explicitly: Use pnpm build:win, pnpm build:mac, or pnpm build:linux for specific platforms
• Locate outputs: Find compiled binaries in desktop/dist/ after the build completes
• Reference configuration: Platform logic resides in desktop/build/platform-*.js files orchestrating electron-builder

Frequently Asked Questions

What Node.js version is required to build escrcpy?

You need Node.js 18 or higher. The repository uses modern pnpm and TurboRepo features that require this minimum version. Verify your installation with node -v before running pnpm install.

Can I build for Windows on macOS or Linux?

Yes, you can target Windows from macOS or Linux by running pnpm build:win, but you must install cross-compilation dependencies such as Wine for Windows code signing and executable generation. The desktop/build/platform-win.js script handles the configuration, but native Windows builds may require additional environment setup for full compatibility.

Where are the compiled binaries located after building?

All build artifacts are written to the desktop/dist/ directory. Subdirectories and filenames include the version number, platform identifier (win, mac, linux), and architecture (x64, arm64), making it easy to identify the correct package for distribution.

How do I clean the build cache before rebuilding?

Run pnpm turbo clean to clear the TurboRepo cache and remove previous build artifacts. This ensures a fresh compilation of TypeScript sources and Vite bundles. After cleaning, execute your desired build command (e.g., pnpm build:linux) to generate clean binaries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}