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