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 zed_visual_test_runner --features visual-tests
73```
74
75### Baseline Images
76
77Baseline images are stored in `crates/zed/test_fixtures/visual_tests/` but are
78**gitignored** to avoid bloating the repository. You must generate them locally
79before running tests.
80
81#### Initial Setup
82
83Before making any UI changes, generate baseline images from a known-good state:
84
85```sh
86git checkout origin/main
87UPDATE_BASELINE=1 cargo run -p zed --bin visual_test_runner --features visual-tests
88git checkout -
89```
90
91This creates baselines that reflect the current expected UI.
92
93#### Updating Baselines
94
95When UI changes are intentional, update the baseline images after your changes:
96
97```sh
98UPDATE_BASELINE=1 cargo run -p zed --bin zed_visual_test_runner --features visual-tests
99```
100
101> **Note:** In the future, baselines may be stored externally. For now, they
102> remain local-only to keep the git repository lightweight.
103
104## Troubleshooting
105
106### Error compiling metal shaders
107
108```sh
109error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
110
111xcrun: error: unable to find utility "metal", not a developer tool or in PATH
112```
113
114Try `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
115
116If you're on macOS 26, try `xcodebuild -downloadComponent MetalToolchain`
117
118### Cargo errors claiming that a dependency is using unstable features
119
120Try `cargo clean` and `cargo build`.
121
122### Error: 'dispatch/dispatch.h' file not found
123
124If you encounter an error similar to:
125
126```sh
127src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found
128
129Caused by:
130 process didn't exit successfully
131
132 --- stdout
133 cargo:rustc-link-lib=framework=System
134 cargo:rerun-if-changed=src/platform/mac/dispatch.h
135 cargo:rerun-if-env-changed=TARGET
136 cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64-apple-darwin
137 cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_darwin
138 cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
139```
140
141This file is part of Xcode. Ensure you have installed the Xcode command line tools and set the correct path:
142
143```sh
144xcode-select --install
145sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
146```
147
148Additionally, set the `BINDGEN_EXTRA_CLANG_ARGS` environment variable:
149
150```sh
151export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"
152```
153
154Then clean and rebuild the project:
155
156```sh
157cargo clean
158cargo run
159```
160
161### Tests failing due to `Too many open files (os error 24)`
162
163This error seems to be caused by OS resource constraints. Installing and running tests with `cargo-nextest` should resolve the issue.
164
165- `cargo install cargo-nextest --locked`
166- `cargo nextest run --workspace --no-fail-fast`
167
168## Tips & Tricks
169
170### Avoiding continual rebuilds
171
172If you are finding that Zed is continually rebuilding root crates, it may be because
173you are pointing your development Zed at the codebase itself.
174
175This causes problems because `cargo run` exports a bunch of environment
176variables which are picked up by the `rust-analyzer` that runs in the development
177build of Zed. These environment variables are in turn passed to `cargo check`, which
178invalidates the build cache of some of the crates we depend on.
179
180You can easily avoid running the built binary on the checked-out Zed codebase using `cargo run
181~/path/to/other/project` to ensure that you don't hit this.
182
183### Speeding up verification
184
185If you are building Zed a lot, you may find that macOS continually verifies new
186builds which can add a few seconds to your iteration cycles.
187
188To fix this, you can:
189
190- Run `sudo spctl developer-mode enable-terminal` to enable the Developer Tools panel in System Settings.
191- 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"
192- Restart your terminal.
193
194Thanks to the nextest developers for publishing [this](https://nexte.st/docs/installation/macos/#gatekeeper).