zed/docs/building-zed.md

⬅ Back to Index

Building Zed

How to build Zed from source for the first time.

Process

Expect this to take 30min to an hour! Some of these steps will take quite a while based on your connection speed, and how long your first build will be.

1. Install the GitHub CLI:
   • brew install gh
2. Clone the zed repo
   • gh repo clone zed-industries/zed
3. Install Xcode from the macOS App Store
4. Install Postgres
5. Install rust/rustup
   • curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
6. Install the wasm toolchain
   • rustup target add wasm32-wasi
7. Generate an GitHub API Key
   • Go to https://github.com/settings/tokens and Generate new token
   • GitHub currently provides two kinds of tokens:
     • Classic Tokens, where only repo (Full control of private repositories) OAuth scope has to be selected Unfortunately, unselecting repo scope and selecting every its inner scope instead does not allow the token users to read from private repositories
     • (not applicable) Fine-grained Tokens, at the moment of writing, did not allow any kind of access of non-owned private repos
   • Keep the token in the browser tab/editor for the next two steps
8. Open Postgres.app
9. From ./path/to/zed/:
   • Run:
     • GITHUB_TOKEN={yourGithubAPIToken} script/bootstrap
     • Replace {yourGithubAPIToken} with the API token you generated above.
   • Consider removing the token (if it's fine for you to crecreate such tokens during occasional migrations) or store this token somewhere safe (like your Zed 1Password vault).
   • If you get:

     • Error: Cannot install in Homebrew on ARM processor in Intel default prefix (/usr/local)!
       Please create a new installation in /opt/homebrew using one of the
       "Alternative Installs" from:
       https://docs.brew.sh/Installation
       

     • In that case try:
       • /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   • If Homebrew is not in your PATH:
     • Replace {username} with your home folder name (usually your login name)
     • echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/{username}/.zprofile
     • eval "$(/opt/homebrew/bin/brew shellenv)"
10. To run the Zed app:
    • If you are working on zed:
      • cargo run
    • If you are just using the latest version, but not working on zed:
      • cargo run --release
    • If you need to run the collaboration server locally:
      • script/zed-with-local-servers

Troubleshooting

error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)

• Try xcode-select --switch /Applications/Xcode.app/Contents/Developer

xcrun: error: unable to find utility "metal", not a developer tool or in PATH

Seeding errors during script/bootstrap runs

seeding database...
thread 'main' panicked at 'failed to deserialize github user from 'https://api.github.com/orgs/zed-industries/teams/staff/members': reqwest::Error { kind: Decode, source: Error("invalid type: map, expected a sequence", line: 1, column: 0) }', crates/collab/src/bin/seed.rs:111:10

Wrong permissions for GITHUB_TOKEN token used, the token needs to be able to read from private repos. For Classic GitHub Tokens, that required OAuth scope repo (seacrh the scope name above for more details)

Same command

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

If you experience errors that mention some dependency is using unstable features

Try cargo clean and cargo build