How to Build the Warp Terminal from Source: A Complete Developer Guide

Building Warp from source requires running ./script/bootstrap to install platform-specific dependencies followed by ./script/run to compile and launch the terminal on macOS, Linux, or Windows.

The Warp terminal is an open-source Rust project hosted at warpdotdev/warp that provides a modern GPU-accelerated terminal experience. Learning how to build the Warp terminal from source enables developers to contribute patches, test bleeding-edge features, or customize the application for specific workflows. This guide walks through the exact build system used by core maintainers, referencing the actual scripts and manifests in the repository.

Bootstrap the Development Environment

The first step to build the Warp terminal from source is initializing your development environment using the entry point script at script/bootstrap. This script detects your host operating system and delegates to platform-specific installers that handle toolchain installation and system dependencies.

macOS Setup

On macOS, the bootstrapper executes script/macos/bootstrap to install Xcode command-line tools, Rust toolchain, and other macOS-specific dependencies required for building the signed application bundle.

Linux Setup

The Linux bootstrapper at script/linux/bootstrap installs apt packages, test dependencies, linuxdeploy tools for AppImage generation, and configures gcloud authentication for internal testing workflows.

Windows Setup

Windows developers run script/windows/bootstrap.ps1, which installs the required Visual Studio build tools, Rustup, and Windows-specific system libraries through PowerShell.

Build and Launch Warp

Once dependencies are installed, use the cross-platform driver at script/run to compile and execute the terminal. This wrapper script performs several critical functions: it sets necessary environment variables, selects the correct binary target (warp for internal builds or warp-oss for the open-source channel), and invokes cargo run with the appropriate feature flags.

The typical workflow for Linux, macOS, or WSL is:

./script/bootstrap
./script/run

Platform-Specific Build Behavior

While the script/run entry point works across all platforms, the underlying behavior varies by operating system. On macOS, the script delegates to script/macos/run, which builds a signed .app bundle suitable for distribution. On Linux and Windows, the script runs cargo run directly against the selected binary target without additional packaging steps.

Build the Core Terminal Library Only

If you only need the terminal logic without the full UI or application shell, you can build the warp_terminal crate independently. This is useful for Headless implementations or when integrating Warp's terminal emulation into custom applications.

The crate manifest lives at crates/warp_terminal/Cargo.toml, with the public API exposed through crates/warp_terminal/src/lib.rs via the model and shell modules. To build the library:

cd crates/warp_terminal
cargo build --features gui

Customize the Build Configuration

The build system supports extensive customization through feature flags, release profiles, and argument forwarding.

Feature Flags

You can pass additional Cargo features using the --features flag. The script/run wrapper also maintains backward compatibility by translating deprecated feature names—including with_local_server, with_local_session_sharing_server, and with_sandbox_telemetry—into corresponding environment variables before invoking Cargo.

Release Builds and Profiles

To compile an optimized release binary instead of a debug build, append the --release flag to the run script. The wrapper also supports custom profiles via --profile <profile>, forwarding these flags directly to the underlying cargo build command.

Passing Arguments to the Binary

Separate arguments intended for the Warp binary from wrapper flags using the -- separator. For example, to display Warp's help text after building:

./script/run -- --help

Summary

• Run ./script/bootstrap to install platform-specific dependencies via the delegation scripts located at script/macos/bootstrap, script/linux/bootstrap, or script/windows/bootstrap.ps1.
• Execute ./script/run to build and launch the terminal, which automatically selects between the warp-oss binary (open-source channel) and warp binary (internal builds) while setting required environment variables.
• Build the core library independently by running cargo build --features gui inside crates/warp_terminal when you need the terminal API without the full application UI.
• Customize compilation by passing --release, --features, or --profile flags to the run script, and use -- to separate wrapper arguments from binary arguments.

Frequently Asked Questions

What dependencies are installed by the bootstrap script?

The script/bootstrap entry point detects your operating system and delegates to specialized installers. On Linux, script/linux/bootstrap installs apt packages, test dependencies, linuxdeploy tools, and configures gcloud authentication. macOS and Windows use their respective script/macos/bootstrap and script/windows/bootstrap.ps1 scripts to install platform-specific toolchains and system libraries.

Can I build Warp without the GUI components?

Yes. Navigate to crates/warp_terminal and run cargo build --features gui to compile only the terminal library. This crate exposes the public API through modules like model and shell defined in crates/warp_terminal/src/lib.rs, making it suitable for headless implementations or custom UI integrations that consume the terminal logic directly.

How do I create a production release build instead of a debug build?

Append the --release flag to the run script invocation: ./script/run --release. The script forwards this flag (along with any --profile <profile> specification) directly to Cargo. You can combine this with feature flags or arguments intended for the Warp binary by placing them after the -- separator.

Why does the build process differ between macOS and Linux?

The script/run wrapper adapts to platform-specific packaging requirements. On macOS, it delegates to script/macos/run to produce a signed .app bundle required for proper application behavior on macOS. On Linux and Windows, the script invokes cargo run directly without additional packaging, as these platforms do not require signed application bundles for development builds.

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