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

> Build the Warp terminal from source on macOS Linux or Windows. Our guide details dependency installation compilation and launching for developers.

- Repository: [Warp/warp](https://github.com/warpdotdev/warp)
- Tags: how-to-guide
- Published: 2026-04-30

---

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

```bash
./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`](https://github.com/warpdotdev/warp/blob/main/crates/warp_terminal/Cargo.toml), with the public API exposed through [`crates/warp_terminal/src/lib.rs`](https://github.com/warpdotdev/warp/blob/main/crates/warp_terminal/src/lib.rs) via the `model` and `shell` modules. To build the library:

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

```bash
./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`](https://github.com/warpdotdev/warp/blob/main/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.