Building Zed for macOS

Repository

Clone down the Zed repository.

Dependencies

• Install rustup

• Install Xcode from the macOS App Store, or from the Apple Developer website. Note this requires a developer account.

Ensure you launch Xcode after installing, and install the macOS components, which is the default option.

• Install Xcode command line tools

  sh

  1	xcode-select --install

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

  sh

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

• Install cmake (required by a dependency)

  sh

  1	brew install cmake

Building Zed from Source

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

For a debug build:

For a release build:

And to run the tests:

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

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:

This creates baselines that reflect the current expected UI.

Updating Baselines

When UI changes are intentional, update the baseline images after your changes:

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

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 and cargo build.

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

If you encounter an error similar to:

This file is part of Xcode. Ensure you have installed the Xcode command line tools and set the correct path:

Additionally, set the BINDGEN_EXTRA_CLANG_ARGS environment variable:

Then clean and rebuild the project:

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 you are finding that Zed is continually rebuilding root crates, it may be because you are pointing your development Zed at the codebase itself.

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.

You can easily avoid running the built binary on the checked-out Zed codebase using cargo run ~/path/to/other/project to ensure that you don't hit this.

Speeding up verification

If you are building Zed a lot, you may find that macOS continually verifies new builds which can add a few seconds to your iteration cycles.

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.