1---
2title: Building Zed for macOS
3description: "Guide to building zed for macos for Zed development."
4---
5
6# Building Zed for macOS
7
8## Repository
9
10Clone the [Zed repository](https://github.com/zed-industries/zed).
11
12## Dependencies
13
14- Install [rustup](https://www.rust-lang.org/tools/install)
15
16- Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) from the macOS App Store or from the [Apple Developer](https://developer.apple.com/download/all/) website. The Apple Developer download requires a developer account.
17
18> Launch Xcode after installation and install the macOS components (the default option).
19
20- Install [Xcode command line tools](https://developer.apple.com/xcode/resources/)
21
22 ```sh
23 xcode-select --install
24 ```
25
26- Ensure that the Xcode command line tools are using your newly installed copy of Xcode:
27
28 ```sh
29 sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
30 sudo xcodebuild -license accept
31 ```
32
33- Install `cmake` (required by [a dependency](https://docs.rs/wasmtime-c-api-impl/latest/wasmtime_c_api/))
34
35 ```sh
36 brew install cmake
37 ```
38
39## Building Zed from Source
40
41Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
42
43For a debug build:
44
45```sh
46cargo run
47```
48
49For a release build:
50
51```sh
52cargo run --release
53```
54
55And to run the tests:
56
57```sh
58cargo test --workspace
59```
60
61## Visual Regression Tests
62
63Zed 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.
64
65### Prerequisites
66
67You must grant Screen Recording permission to your terminal:
68
691. Run the visual test runner once - macOS will prompt for permission
702. Or manually: System Settings > Privacy & Security > Screen Recording
713. Enable your terminal app (e.g., Terminal.app, iTerm2, Ghostty)
724. Restart your terminal after granting permission
73
74### Running Visual Tests
75
76```sh
77cargo run -p zed --bin zed_visual_test_runner --features visual-tests
78```
79
80### Baseline Images
81
82Baseline images are stored in `crates/zed/test_fixtures/visual_tests/` but are
83**gitignored** to avoid bloating the repository. You must generate them locally
84before running tests.
85
86#### Initial Setup
87
88Before making any UI changes, generate baseline images from a known-good state:
89
90```sh
91git checkout origin/main
92UPDATE_BASELINE=1 cargo run -p zed --bin visual_test_runner --features visual-tests
93git checkout -
94```
95
96This creates baselines that reflect the current expected UI.
97
98#### Updating Baselines
99
100When UI changes are intentional, update the baseline images after your changes:
101
102```sh
103UPDATE_BASELINE=1 cargo run -p zed --bin zed_visual_test_runner --features visual-tests
104```
105
106> **Note:** In the future, baselines may be stored externally. For now, they
107> remain local-only to keep the git repository lightweight.
108
109## Troubleshooting
110
111### Error compiling metal shaders
112
113```sh
114error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
115
116xcrun: error: unable to find utility "metal", not a developer tool or in PATH
117```
118
119Try `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
120
121If you're on macOS 26, try `xcodebuild -downloadComponent MetalToolchain`
122
123### Cargo errors claiming that a dependency is using unstable features
124
125Try `cargo clean` and `cargo build`.
126
127### Error: 'dispatch/dispatch.h' file not found
128
129If you encounter an error similar to:
130
131```sh
132src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found
133
134Caused by:
135 process didn't exit successfully
136
137 --- stdout
138 cargo:rustc-link-lib=framework=System
139 cargo:rerun-if-changed=src/platform/mac/dispatch.h
140 cargo:rerun-if-env-changed=TARGET
141 cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64-apple-darwin
142 cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_darwin
143 cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
144```
145
146This file is part of Xcode. Make sure the Xcode command line tools are installed and the path is set correctly:
147
148```sh
149xcode-select --install
150sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
151```
152
153Additionally, set the `BINDGEN_EXTRA_CLANG_ARGS` environment variable:
154
155```sh
156export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"
157```
158
159Then clean and rebuild the project:
160
161```sh
162cargo clean
163cargo run
164```
165
166### Tests failing due to `Too many open files (os error 24)`
167
168This error seems to be caused by OS resource constraints. Installing and running tests with `cargo-nextest` should resolve the issue.
169
170- `cargo install cargo-nextest --locked`
171- `cargo nextest run --workspace --no-fail-fast`
172
173## Tips & Tricks
174
175### Avoiding continual rebuilds
176
177If Zed continually rebuilds root crates, you may be opening the Zed codebase itself in your development build.
178
179This causes problems because `cargo run` exports a bunch of environment
180variables which are picked up by the `rust-analyzer` that runs in the development
181build of Zed. These environment variables are in turn passed to `cargo check`, which
182invalidates the build cache of some of the crates we depend on.
183
184To avoid this, run the built binary against a different project, for example `cargo run ~/path/to/other/project`.
185
186### Speeding up verification
187
188If you build Zed frequently, macOS may keep verifying new builds, which can add a few seconds to each iteration.
189
190To fix this, you can:
191
192- Run `sudo spctl developer-mode enable-terminal` to enable the Developer Tools panel in System Settings.
193- 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"
194- Restart your terminal.
195
196Thanks to the nextest developers for publishing [this](https://nexte.st/docs/installation/macos/#gatekeeper).