Getting started

This page covers building Zed from source. The canonical user-facing documentation lives in docs/src/development/ and on zed.dev/docs. This page summarizes what a contributor needs to know.

Prerequisites

Zed builds on macOS, Linux, and Windows. The full per-platform guides are:

• macOS: docs/src/development/macos.md
• Linux: docs/src/development/linux.md
• Windows: docs/src/development/windows.md

You will need:

• A recent stable Rust toolchain (the workspace currently targets Rust 1.95+; see rust-toolchain.toml).
• Cargo's standard tooling (cargo, rustup).
• Node.js — Zed uses a managed Node runtime (node_runtime) at runtime, but a system Node is convenient for some scripts.
• Platform-specific GUI/dev libraries (X11/Wayland on Linux, MSVC build tools on Windows).

There is a bootstrap script that installs platform dependencies on a clean machine: script/bootstrap (POSIX) or script/bootstrap.ps1 (Windows).

Common commands

Run from the repo root:

cargo run                             # debug build of the editor (zed binary)
cargo run --release                   # optimized build
cargo run --bin cli                   # the CLI launcher
cargo run --bin collab -- serve api   # the collaboration backend
cargo run --bin remote_server         # the remote-development server
cargo test                            # all tests
./script/clippy                        # lint via the project wrapper (NOT raw cargo clippy)

Use ./script/clippy rather than cargo clippy directly — the wrapper sets workspace-specific flags. This is enforced by the .rules file.

Build profiles

The workspace defines several profiles in Cargo.toml:

• dev — default debug build.
• release — production release.
• release-fast — faster compile, slightly less optimized; commonly used for local "release-ish" testing.
• test and bench — tuned for tests and benches respectively.

You will see --profile release-fast referenced in scripts and CI for cases where startup time matters but full release optimization is overkill.

Running tests

cargo test                            # everything
cargo test -p editor                  # one crate
cargo test -p gpui --test focus       # one test file
cargo nextest run -p editor           # via nextest if installed

Visual regression tests (UI snapshot tests) run via the visual-tests feature on the zed crate. See script/test-visual-regression and crates/zed/src/visual_test_runner.rs. The macOS dev guide (docs/src/development/macos.md) covers how to update snapshots.

Running Zed locally

cargo run                             # opens an empty workspace
cargo run -- path/to/folder           # opens a folder
cargo run -- --foreground             # run with logs to stderr
cargo run --features track-project-leak   # leak detection

Running the collab backend

The collab server can be brought up locally for end-to-end testing of multiplayer features. See crates/collab/README.md and compose.yml. There is also a Procfile and Procfile.all for running the editor + collab together (for example via foreman or overmind).

Useful scripts

The script/ directory has 100+ helpers. Highlights:

Script	What it does
script/bootstrap	Install OS-level build deps
script/clippy	Run clippy with the project's flags
script/check-keymaps	Validate the bundled keymaps
script/check-licenses	Validate dependency licenses (cargo-about)
script/check-todos	Sweep for stale TODO/FIXME annotations
script/sentry-fetch <issue-id>	Pull a crash report from Sentry
script/crash-to-prompt <issue-id>	Turn a Sentry crash into an investigation prompt
script/bundle-{mac,linux}	Produce platform installers
script/cherry-pick	Cherry-pick onto release branches
script/draft-release-notes	Generate release notes from PRs since a given tag

Debug and crash investigation

Zed integrates with Sentry. Crash investigation prompts live under .factory/prompts/crash/:

• script/sentry-fetch <issue-id> — fetch a crash
• script/crash-to-prompt <issue-id> — turn it into an investigation prompt for an AI session

For local debugging, see Debugging.