1# Building Zed for Windows
  2
  3> The following commands may be executed in any shell.
  4
  5## Repository
  6
  7Clone down the [Zed repository](https://github.com/zed-industries/zed).
  8
  9## Dependencies
 10
 11- Install either [Visual Studio](https://visualstudio.microsoft.com/downloads/) with the optional components `MSVC v*** - VS YYYY C++ x64/x86 build tools` and `MSVC v*** - VS YYYY C++ x64/x86 Spectre-mitigated libs (latest)` (`v***` is your VS version and `YYYY` is year when your VS was released. Pay attention to the architecture and change it to yours if needed.)
 12- Or, if you prefer to have a slimmer installer of only the MSVC compiler tools, you can install the [build tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (+libs as above) and the "Desktop development with C++" workload.
 13  But beware this installation is not automatically picked up by rustup. You must initialize your environment variables by first launching the "developer" shell (cmd/powershell) this installation places in the start menu or in Windows Terminal and then compile.
 14- Install [rustup](https://www.rust-lang.org/tools/install).
 15- Install Windows 11 or 10 SDK depending on your system, but ensure that at least `Windows 10 SDK version 2104 (10.0.20348.0)` is installed on your machine. You can download it from the [Windows SDK Archive](https://developer.microsoft.com/windows/downloads/windows-sdk/)
 16- Install [CMake](https://cmake.org/download) (required by [a dependency](https://docs.rs/wasmtime-c-api-impl/latest/wasmtime_c_api/)), if it was not installed by the Visual Studio Installer. (If you used the Visual Studio Installer, you may need to manually add the `bin` directory to your `PATH`, for example: `C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin`.)
 17
 18If you can't compile Zed, make sure that you have at least the following components installed in case of a Visual Studio installation:
 19
 20```json
 21{
 22  "version": "1.0",
 23  "components": [
 24    "Microsoft.VisualStudio.Component.CoreEditor",
 25    "Microsoft.VisualStudio.Workload.CoreEditor",
 26    "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
 27    "Microsoft.VisualStudio.ComponentGroup.WebToolsExtensions.CMake",
 28    "Microsoft.VisualStudio.Component.VC.CMake.Project",
 29    "Microsoft.VisualStudio.Component.Windows11SDK.26100",
 30    "Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre"
 31  ],
 32  "extensions": []
 33}
 34```
 35
 36Or if in case of just Build Tools, the following components:
 37
 38```json
 39{
 40  "version": "1.0",
 41  "components": [
 42    "Microsoft.VisualStudio.Component.Roslyn.Compiler",
 43    "Microsoft.Component.MSBuild",
 44    "Microsoft.VisualStudio.Component.CoreBuildTools",
 45    "Microsoft.VisualStudio.Workload.MSBuildTools",
 46    "Microsoft.VisualStudio.Component.Windows10SDK",
 47    "Microsoft.VisualStudio.Component.VC.CoreBuildTools",
 48    "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
 49    "Microsoft.VisualStudio.Component.VC.Redist.14.Latest",
 50    "Microsoft.VisualStudio.Component.Windows11SDK.26100",
 51    "Microsoft.VisualStudio.Component.VC.CMake.Project",
 52    "Microsoft.VisualStudio.Component.TextTemplating",
 53    "Microsoft.VisualStudio.Component.VC.CoreIde",
 54    "Microsoft.VisualStudio.ComponentGroup.NativeDesktop.Core",
 55    "Microsoft.VisualStudio.Workload.VCTools",
 56    "Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre"
 57  ],
 58  "extensions": []
 59}
 60```
 61
 62The list can be obtained as follows:
 63
 64- Open the Visual Studio Installer
 65- Click on `More` in the `Installed` tab
 66- Click on `Export configuration`
 67
 68## Backend dependencies
 69
 70> This section is still in development. The instructions are not yet complete.
 71
 72If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's `collab` server:
 73
 74- Install [Postgres](https://www.postgresql.org/download/windows/)
 75- Install [Livekit](https://github.com/livekit/livekit), optionally you can add the `livekit-server` binary to your `PATH`.
 76
 77Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose:
 78
 79```sh
 80docker compose up -d
 81```
 82
 83### Notes
 84
 85You should modify the `pg_hba.conf` file in the `data` directory to use `trust` instead of `scram-sha-256` for the `host` method. Otherwise, the connection will fail with the error `password authentication failed`. The `pg_hba.conf` file typically locates at `C:\Program Files\PostgreSQL\17\data\pg_hba.conf`. After the modification, the file should look like this:
 86
 87```conf
 88# IPv4 local connections:
 89host    all             all             127.0.0.1/32            trust
 90# IPv6 local connections:
 91host    all             all             ::1/128                 trust
 92```
 93
 94Also, if you are using a non-latin Windows version, you must modify the`lc_messages` parameter in the `postgresql.conf` file in the `data` directory to `English_United States.1252` (or whatever UTF8-compatible encoding you have). Otherwise, the database will panic. The `postgresql.conf` file should look like this:
 95
 96```conf
 97# lc_messages = 'Chinese (Simplified)_China.936' # locale for system error message strings
 98lc_messages = 'English_United States.1252'
 99```
100
101After this, you should restart the `postgresql` service. Press the `win` key + `R` to launch the `Run` window. Type the `services.msc` and hit the `OK` button to open the Services Manager. Then, find the `postgresql-x64-XX` service, right-click on it, and select `Restart`.
102
103## Building from source
104
105Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
106
107For a debug build:
108
109```sh
110cargo run
111```
112
113For a release build:
114
115```sh
116cargo run --release
117```
118
119And to run the tests:
120
121```sh
122cargo test --workspace
123```
124
125## Installing from msys2
126
127[MSYS2](https://msys2.org/) distribution provides Zed as a package [mingw-w64-zed](https://packages.msys2.org/base/mingw-w64-zed). The package is available for UCRT64, MINGW64 and CLANG64 repositories. To download it, run
128
129```sh
130pacman -Syu
131pacman -S $MINGW_PACKAGE_PREFIX-zed
132```
133
134then you can run `zeditor` CLI. Editor executable is installed under `$MINGW_PREFIX/lib/zed` directory
135
136You can see the [build script](https://github.com/msys2/MINGW-packages/blob/master/mingw-w64-zed/PKGBUILD) for more details on build process.
137
138> Please, report any issue in [msys2/MINGW-packages/issues](https://github.com/msys2/MINGW-packages/issues?q=is%3Aissue+is%3Aopen+zed) first.
139
140Note that `collab` is not supported for MSYS2.
141
142## Troubleshooting
143
144### Setting `RUSTFLAGS` env var breaks builds
145
146If you set the `RUSTFLAGS` env var, it will override the `rustflags` settings in `.cargo/config.toml` which is required to properly build Zed.
147
148Since these settings can vary from time to time, the build errors you receive may vary from linker errors, to other stranger errors.
149
150If you'd like to add extra rust flags, you may do 1 of the following in `.cargo/config.toml`:
151
152Add your flags in the build section
153
154```toml
155[build]
156rustflags = ["-C", "symbol-mangling-version=v0", "--cfg", "tokio_unstable"]
157```
158
159Add your flags in the windows target section
160
161```toml
162[target.'cfg(target_os = "windows")']
163rustflags = [
164    "--cfg",
165    "windows_slim_errors",
166    "-C",
167    "target-feature=+crt-static",
168]
169```
170
171Or, you can create a new `.cargo/config.toml` in the same folder as the Zed repo (see below). This is particularly useful if you are doing CI builds since you don't have to edit the original `.cargo/config.toml`.
172
173```
174upper_dir
175├── .cargo          // <-- Make this folder
176│   └── config.toml // <-- Make this file
177└── zed
178    ├── .cargo
179    │   └── config.toml
180    └── crates
181        ├── assistant
182        └── ...
183```
184
185In the new (above) `.cargo/config.toml`, if we wanted to add `--cfg gles` to our rustflags, it would look like this
186
187```toml
188[target.'cfg(all())']
189rustflags = ["--cfg", "gles"]
190```
191
192### Cargo errors claiming that a dependency is using unstable features
193
194Try `cargo clean` and `cargo build`.
195
196### `STATUS_ACCESS_VIOLATION`
197
198This error can happen if you are using the "rust-lld.exe" linker. Consider trying a different linker.
199
200If you are using a global config, consider moving the Zed repository to a nested directory and add a `.cargo/config.toml` with a custom linker config in the parent directory.
201
202See this issue for more information [#12041](https://github.com/zed-industries/zed/issues/12041)
203
204### Invalid RC path selected
205
206Sometimes, depending on the security rules applied to your laptop, you may get the following error while compiling Zed:
207
208```
209error: failed to run custom build command for `zed(C:\Users\USER\src\zed\crates\zed)`
210
211Caused by:
212  process didn't exit successfully: `C:\Users\USER\src\zed\target\debug\build\zed-b24f1e9300107efc\build-script-build` (exit code: 1)
213  --- stdout
214  cargo:rerun-if-changed=../../.git/logs/HEAD
215  cargo:rustc-env=ZED_COMMIT_SHA=25e2e9c6727ba9b77415588cfa11fd969612adb7
216  cargo:rustc-link-arg=/stack:8388608
217  cargo:rerun-if-changed=resources/windows/app-icon.ico
218  package.metadata.winresource does not exist
219  Selected RC path: 'bin\x64\rc.exe'
220
221  --- stderr
222  The system cannot find the path specified. (os error 3)
223warning: build failed, waiting for other jobs to finish...
224```
225
226In order to fix this issue, you can manually set the `ZED_RC_TOOLKIT_PATH` environment variable to the RC toolkit path. Usually, you can set it to:
227`C:\Program Files (x86)\Windows Kits\10\bin\<SDK_version>\x64`.
228
229See this [issue](https://github.com/zed-industries/zed/issues/18393) for more information.
230
231### Build fails: Path too long
232
233You may receive an error like the following when building
234
235```
236error: failed to get `pet` as a dependency of package `languages v0.1.0 (D:\a\zed-windows-builds\zed-windows-builds\crates\languages)`
237
238Caused by:
239  failed to load source for dependency `pet`
240
241Caused by:
242  Unable to update https://github.com/microsoft/python-environment-tools.git?rev=ffcbf3f28c46633abd5448a52b1f396c322e0d6c#ffcbf3f2
243
244Caused by:
245  path too long: 'C:/Users/runneradmin/.cargo/git/checkouts/python-environment-tools-903993894b37a7d2/ffcbf3f/crates/pet-conda/tests/unix/conda_env_without_manager_but_found_in_history/some_other_location/conda_install/conda-meta/python-fastjsonschema-2.16.2-py310hca03da5_0.json'; class=Filesystem (30)
246```
247
248In order to solve this, you can enable longpath support for git and Windows.
249
250For git: `git config --system core.longpaths true`
251
252And for Windows with this PS command:
253
254```powershell
255New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
256```
257
258For more information on this, please see [win32 docs](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell)
259
260(note that you will need to restart your system after enabling longpath support)
261
262### Graphics issues
263
264#### Zed fails to launch
265
266Currently, Zed uses Vulkan as its graphics API on Windows. However, Vulkan isn't always the most reliable on Windows, so if Zed fails to launch, it's likely a Vulkan-related issue.
267
268You can check the Zed log at:
269`C:\Users\YOU\AppData\Local\Zed\logs\Zed.log`
270
271If you see messages like:
272
273- `Zed failed to open a window: NoSupportedDeviceFound`
274- `ERROR_INITIALIZATION_FAILED`
275- `GPU Crashed`
276- `ERROR_SURFACE_LOST_KHR`
277
278Then Vulkan might not be working properly on your system. In most cases, updating your GPU drivers may help resolve this.
279
280If there's nothing Vulkan-related in the logs and you happen to have Bandicam installed, try uninstalling it. Zed is currently not compatible with Bandicam.