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