Skip to main content

​
Building Zed for macOS

​
Clone the Repository

Clone the Zed repository: 
git clone https://github.com/zed-industries/zed.git
cd zed

​
Install Dependencies

​
Rust

Install rustup: 
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

​
Xcode

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).

​
Xcode Command Line Tools

Install the 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

​
CMake

Install CMake (required by a dependency): 
brew install cmake

​
Build Zed from Source

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

​
Debug Build

For a debug build: 
cargo run

​
Release Build

For a release build: 
cargo run --release

​
Run Tests

To run the tests: 
cargo test --workspace

​
Visual Regression Tests

Zed includes visual regression tests that capture screenshots of real Zed windows and compare them against baseline images. These tests require macOS with Screen Recording permission.

​
Prerequisites

You must grant Screen Recording permission to your terminal:
  1. Run the visual test runner once - macOS will prompt for permission
  2. Or manually: System Settings > Privacy & Security > Screen Recording
  3. Enable your terminal app (e.g., Terminal.app, iTerm2, Ghostty)
  4. Restart your terminal after granting permission

​
Running Visual Tests

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

​
Baseline Images

Baseline images are stored in crates/zed/test_fixtures/visual_tests/ but are gitignored to avoid bloating the repository. You must generate them locally before running tests.

​
Initial Setup

Before making any UI changes, generate baseline images from a known-good state: 
git checkout origin/main
UPDATE_BASELINE=1 cargo run -p zed --bin visual_test_runner --features visual-tests
git checkout -
This creates baselines that reflect the current expected UI.

​
Updating Baselines

When UI changes are intentional, update the baseline images after your changes: 
UPDATE_BASELINE=1 cargo run -p zed --bin zed_visual_test_runner --features visual-tests
In the future, baselines may be stored externally. For now, they remain local-only to keep the git repository lightweight.

​
Troubleshooting

​
Error compiling metal shaders

If you see: 
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

​
Cargo errors claiming that a dependency is using unstable features

Try: 
cargo clean
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
  ...
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: 
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:
  1. Run sudo spctl developer-mode enable-terminal to enable the Developer Tools panel in System Settings
  2. 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”
  3. Restart your terminal
Thanks to the nextest developers for publishing this.