Building Zed for macOS

July 30, 2026 · View on GitHub

Dependencies

Install rustup
Install Xcode from the macOS App Store or from the Apple Developer website. The Apple Developer download requires a developer account.

Launch Xcode after installation and install the macOS components (the default option).

Install Xcode command line tools
```
xcode-select --install
```

Ensure that the Xcode command line tools are using your newly installed copy of Xcode:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

Install cmake (required by a dependency)
```
brew install cmake
```

Building Zed from Source

Once you have the dependencies installed, you can build Zed using Cargo.

For a debug build:

cargo run

For a release build:

cargo run --release

And to run the tests:

cargo test --workspace

Zed includes visual regression tests that render real GPUI windows through Metal and compare their textures with baseline images. Direct texture capture does not require Screen Recording permission, does not capture system window chrome, and does not send input to the foreground application.

Prerequisites

Install the Xcode and Metal components described above. Visual comparisons depend on the GPU, font rasterizer, loaded fonts, scale, and theme. Generate authoritative Omega baselines on the project's pinned Apple Silicon Metal environment.

Running Visual Tests

Run Omega's registered workbench scenes with:

script/omega-workbench-proof

Run one scene without capturing a PNG:

script/omega-workbench-proof \
  --scene omega_front_door_no_project \
  --semantic-only

See Deterministic Omega workbench proofs for scene registration, seeds, receipts, artifacts, sharding, and cold-restart behavior.

The lower-level runner remains available while developing visual tests:

cargo run -p zed --bin zed_visual_test_runner --features visual-tests

Baseline Images

Omega's authoritative baseline images are committed in crates/omega/test_fixtures/visual_tests/. Not every inherited visual-runner scene has a committed baseline, so running the lower-level runner without a scene filter can report missing inherited baselines.

Updating Baselines

When an intentional UI change affects a registered Omega scene, update only that scene:

script/omega-workbench-proof \
  --scene omega_front_door_no_project \
  --pixel-only \
  --update

Inspect the current image and changed baseline, then rerun without --update. If that comparison fails, inspect the generated diff image. Baseline updates are disabled in CI.

Troubleshooting

Error compiling metal shaders

error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**

xcrun: error: unable to find utility "metal", not a developer tool or in PATH

Try sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

If you're on macOS 26, try xcodebuild -downloadComponent MetalToolchain. If that command fails, run xcodebuild -runFirstLaunch and try downloading the toolchain again.

Cargo errors claiming that a dependency is using unstable features

Try cargo clean and cargo build.

Error: 'dispatch/dispatch.h' file not found

If you encounter an error similar to:

src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found

Caused by:
  process didn't exit successfully

  --- stdout
  cargo:rustc-link-lib=framework=System
  cargo:rerun-if-changed=src/platform/mac/dispatch.h
  cargo:rerun-if-env-changed=TARGET
  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64-apple-darwin
  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_darwin
  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS

This file is part of Xcode. Make sure the Xcode command line tools are installed and the path is set correctly:

xcode-select --install
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Additionally, set the BINDGEN_EXTRA_CLANG_ARGS environment variable:

export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"

Then clean and rebuild the project:

cargo clean
cargo run

Tests failing due to `Too many open files (os error 24)`

This error seems to be caused by OS resource constraints. Installing and running tests with cargo-nextest should resolve the issue.

cargo install cargo-nextest --locked
cargo nextest run --workspace --no-fail-fast

Tips & Tricks

Avoiding continual rebuilds

If Zed continually rebuilds root crates, you may be opening the Zed codebase itself in your development build.

This causes problems because cargo run exports a bunch of environment variables which are picked up by the rust-analyzer that runs in the development build of Zed. These environment variables are in turn passed to cargo check, which invalidates the build cache of some of the crates we depend on.

To avoid this, run the built binary against a different project, for example cargo run ~/path/to/other/project.

Speeding up verification

If you build Zed frequently, macOS may keep verifying new builds, which can add a few seconds to each iteration.

To fix this, you can:

Run sudo spctl developer-mode enable-terminal to enable the Developer Tools panel in System Settings.
In System Settings, search for "Developer Tools" and add your terminal (e.g. iTerm or Ghostty) to the list under "Allow applications to use developer tools"
Restart your terminal.

Thanks to the nextest developers for publishing this.