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