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 [rustup](https://www.rust-lang.org/tools/install)
 12
 13- 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.)
 14- 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.
 15  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.
 16- 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/)
 17- Install [CMake](https://cmake.org/download) (required by [a dependency](https://docs.rs/wasmtime-c-api-impl/latest/wasmtime_c_api/)). Or you can install it through Visual Studio Installer, then 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`.
 18
 19If you can't compile Zed, make sure that you have at least the following components installed in case of a Visual Studio installation:
 20
 21```json
 22{
 23  "version": "1.0",
 24  "components": [
 25    "Microsoft.VisualStudio.Component.CoreEditor",
 26    "Microsoft.VisualStudio.Workload.CoreEditor",
 27    "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
 28    "Microsoft.VisualStudio.ComponentGroup.WebToolsExtensions.CMake",
 29    "Microsoft.VisualStudio.Component.VC.CMake.Project",
 30    "Microsoft.VisualStudio.Component.Windows11SDK.26100",
 31    "Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre"
 32  ],
 33  "extensions": []
 34}
 35```
 36
 37Or if in case of just Build Tools, the following components:
 38
 39```json
 40{
 41  "version": "1.0",
 42  "components": [
 43    "Microsoft.VisualStudio.Component.Roslyn.Compiler",
 44    "Microsoft.Component.MSBuild",
 45    "Microsoft.VisualStudio.Component.CoreBuildTools",
 46    "Microsoft.VisualStudio.Workload.MSBuildTools",
 47    "Microsoft.VisualStudio.Component.Windows10SDK",
 48    "Microsoft.VisualStudio.Component.VC.CoreBuildTools",
 49    "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
 50    "Microsoft.VisualStudio.Component.VC.Redist.14.Latest",
 51    "Microsoft.VisualStudio.Component.Windows11SDK.26100",
 52    "Microsoft.VisualStudio.Component.VC.CMake.Project",
 53    "Microsoft.VisualStudio.Component.TextTemplating",
 54    "Microsoft.VisualStudio.Component.VC.CoreIde",
 55    "Microsoft.VisualStudio.ComponentGroup.NativeDesktop.Core",
 56    "Microsoft.VisualStudio.Workload.VCTools",
 57    "Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre"
 58  ],
 59  "extensions": []
 60}
 61```
 62
 63The list can be obtained as follows:
 64
 65- Open the Visual Studio Installer
 66- Click on `More` in the `Installed` tab
 67- Click on `Export configuration`
 68
 69### Backend Dependencies (optional) {#backend-dependencies}
 70
 71If you are looking to develop Zed collaboration features using a local collabortation server, please see: [Local Collaboration](./local-collaboration.md) docs.
 72
 73### Notes
 74
 75You 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:
 76
 77```conf
 78# IPv4 local connections:
 79host    all             all             127.0.0.1/32            trust
 80# IPv6 local connections:
 81host    all             all             ::1/128                 trust
 82```
 83
 84Also, 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:
 85
 86```conf
 87# lc_messages = 'Chinese (Simplified)_China.936' # locale for system error message strings
 88lc_messages = 'English_United States.1252'
 89```
 90
 91After 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`.
 92
 93## Building from source
 94
 95Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
 96
 97For a debug build:
 98
 99```sh
100cargo run
101```
102
103For a release build:
104
105```sh
106cargo run --release
107```
108
109And to run the tests:
110
111```sh
112cargo test --workspace
113```
114
115## Installing from msys2
116
117[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, CLANG64 and CLANGARM64 repositories. To download it, run
118
119```sh
120pacman -Syu
121pacman -S $MINGW_PACKAGE_PREFIX-zed
122```
123
124You can see the [build script](https://github.com/msys2/MINGW-packages/blob/master/mingw-w64-zed/PKGBUILD) for more details on build process.
125
126> Please, report any issue in [msys2/MINGW-packages/issues](https://github.com/msys2/MINGW-packages/issues?q=is%3Aissue+is%3Aopen+zed) first.
127
128See also MSYS2 [documentation page](https://www.msys2.org/docs/ides-editors).
129
130Note that `collab` is not supported for MSYS2.
131
132## Troubleshooting
133
134### Setting `RUSTFLAGS` env var breaks builds
135
136If you set the `RUSTFLAGS` env var, it will override the `rustflags` settings in `.cargo/config.toml` which is required to properly build Zed.
137
138Since these settings can vary from time to time, the build errors you receive may vary from linker errors, to other stranger errors.
139
140If you'd like to add extra rust flags, you may do 1 of the following in `.cargo/config.toml`:
141
142Add your flags in the build section
143
144```toml
145[build]
146rustflags = ["-C", "symbol-mangling-version=v0", "--cfg", "tokio_unstable"]
147```
148
149Add your flags in the windows target section
150
151```toml
152[target.'cfg(target_os = "windows")']
153rustflags = [
154    "--cfg",
155    "windows_slim_errors",
156    "-C",
157    "target-feature=+crt-static",
158]
159```
160
161Or, 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`.
162
163```
164upper_dir
165├── .cargo          // <-- Make this folder
166│   └── config.toml // <-- Make this file
167└── zed
168    ├── .cargo
169    │   └── config.toml
170    └── crates
171        ├── assistant
172        └── ...
173```
174
175In the new (above) `.cargo/config.toml`, if we wanted to add `--cfg gles` to our rustflags, it would look like this
176
177```toml
178[target.'cfg(all())']
179rustflags = ["--cfg", "gles"]
180```
181
182### Cargo errors claiming that a dependency is using unstable features
183
184Try `cargo clean` and `cargo build`.
185
186### `STATUS_ACCESS_VIOLATION`
187
188This error can happen if you are using the "rust-lld.exe" linker. Consider trying a different linker.
189
190If 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.
191
192See this issue for more information [#12041](https://github.com/zed-industries/zed/issues/12041)
193
194### Invalid RC path selected
195
196Sometimes, depending on the security rules applied to your laptop, you may get the following error while compiling Zed:
197
198```
199error: failed to run custom build command for `zed(C:\Users\USER\src\zed\crates\zed)`
200
201Caused by:
202  process didn't exit successfully: `C:\Users\USER\src\zed\target\debug\build\zed-b24f1e9300107efc\build-script-build` (exit code: 1)
203  --- stdout
204  cargo:rerun-if-changed=../../.git/logs/HEAD
205  cargo:rustc-env=ZED_COMMIT_SHA=25e2e9c6727ba9b77415588cfa11fd969612adb7
206  cargo:rustc-link-arg=/stack:8388608
207  cargo:rerun-if-changed=resources/windows/app-icon.ico
208  package.metadata.winresource does not exist
209  Selected RC path: 'bin\x64\rc.exe'
210
211  --- stderr
212  The system cannot find the path specified. (os error 3)
213warning: build failed, waiting for other jobs to finish...
214```
215
216In 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:
217`C:\Program Files (x86)\Windows Kits\10\bin\<SDK_version>\x64`.
218
219See this [issue](https://github.com/zed-industries/zed/issues/18393) for more information.
220
221### Build fails: Path too long
222
223You may receive an error like the following when building
224
225```
226error: failed to get `pet` as a dependency of package `languages v0.1.0 (D:\a\zed-windows-builds\zed-windows-builds\crates\languages)`
227
228Caused by:
229  failed to load source for dependency `pet`
230
231Caused by:
232  Unable to update https://github.com/microsoft/python-environment-tools.git?rev=ffcbf3f28c46633abd5448a52b1f396c322e0d6c#ffcbf3f2
233
234Caused by:
235  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)
236```
237
238In order to solve this, you can enable longpath support for git and Windows.
239
240For git: `git config --system core.longpaths true`
241
242And for Windows with this PS command:
243
244```powershell
245New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
246```
247
248For more information on this, please see [win32 docs](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell)
249
250(note that you will need to restart your system after enabling longpath support)
251
252### Graphics issues
253
254#### Zed fails to launch
255
256Currently, 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.
257
258You can check the Zed log at:
259`C:\Users\YOU\AppData\Local\Zed\logs\Zed.log`
260
261If you see messages like:
262
263- `Zed failed to open a window: NoSupportedDeviceFound`
264- `ERROR_INITIALIZATION_FAILED`
265- `GPU Crashed`
266- `ERROR_SURFACE_LOST_KHR`
267
268Then Vulkan might not be working properly on your system. In most cases, updating your GPU drivers may help resolve this.
269
270If 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.