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## Troubleshooting
 57
 58### Error compiling metal shaders
 59
 60```sh
 61error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
 62
 63xcrun: error: unable to find utility "metal", not a developer tool or in PATH
 64```
 65
 66Try `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
 67
 68If you're on macOS 26, try `xcodebuild -downloadComponent MetalToolchain`
 69
 70### Cargo errors claiming that a dependency is using unstable features
 71
 72Try `cargo clean` and `cargo build`.
 73
 74### Error: 'dispatch/dispatch.h' file not found
 75
 76If you encounter an error similar to:
 77
 78```sh
 79src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found
 80
 81Caused by:
 82  process didn't exit successfully
 83
 84  --- stdout
 85  cargo:rustc-link-lib=framework=System
 86  cargo:rerun-if-changed=src/platform/mac/dispatch.h
 87  cargo:rerun-if-env-changed=TARGET
 88  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64-apple-darwin
 89  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_darwin
 90  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
 91```
 92
 93This file is part of Xcode. Ensure you have installed the Xcode command line tools and set the correct path:
 94
 95```sh
 96xcode-select --install
 97sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
 98```
 99
100Additionally, set the `BINDGEN_EXTRA_CLANG_ARGS` environment variable:
101
102```sh
103export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"
104```
105
106Then clean and rebuild the project:
107
108```sh
109cargo clean
110cargo run
111```
112
113### Tests failing due to `Too many open files (os error 24)`
114
115This error seems to be caused by OS resource constraints. Installing and running tests with `cargo-nextest` should resolve the issue.
116
117- `cargo install cargo-nextest --locked`
118- `cargo nextest run --workspace --no-fail-fast`
119
120## Tips & Tricks
121
122### Avoiding continual rebuilds
123
124If you are finding that Zed is continually rebuilding root crates, it may be because
125you are pointing your development Zed at the codebase itself.
126
127This causes problems because `cargo run` exports a bunch of environment
128variables which are picked up by the `rust-analyzer` that runs in the development
129build of Zed. These environment variables are in turn passed to `cargo check`, which
130invalidates the build cache of some of the crates we depend on.
131
132You can easily avoid running the built binary on the checked-out Zed codebase using `cargo run
133~/path/to/other/project` to ensure that you don't hit this.
134
135### Speeding up verification
136
137If you are building Zed a lot, you may find that macOS continually verifies new
138builds which can add a few seconds to your iteration cycles.
139
140To fix this, you can:
141
142- Run `sudo spctl developer-mode enable-terminal` to enable the Developer Tools panel in System Settings.
143- 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"
144- Restart your terminal.
145
146Thanks to the nextest developers for publishing [this](https://nexte.st/docs/installation/macos/#gatekeeper).