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 [settings]
 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 [settings]
 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### Notes
 70
 71You 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:
 72
 73```conf
 74# IPv4 local connections:
 75host    all             all             127.0.0.1/32            trust
 76# IPv6 local connections:
 77host    all             all             ::1/128                 trust
 78```
 79
 80Also, 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:
 81
 82```conf
 83# lc_messages = 'Chinese (Simplified)_China.936' # locale for system error message strings
 84lc_messages = 'English_United States.1252'
 85```
 86
 87After 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`.
 88
 89## Building from source
 90
 91Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
 92
 93For a debug build:
 94
 95```sh
 96cargo run
 97```
 98
 99For a release build:
100
101```sh
102cargo run --release
103```
104
105And to run the tests:
106
107```sh
108cargo test --workspace
109```
110
111## Installing from msys2
112
113Zed does not support unofficial MSYS2 Zed packages built for Mingw-w64. Please report any issues you may have with [mingw-w64-zed](https://packages.msys2.org/base/mingw-w64-zed) to [msys2/MINGW-packages/issues](https://github.com/msys2/MINGW-packages/issues?q=is%3Aissue+is%3Aopen+zed).
114
115Please refer to [MSYS2 documentation](https://www.msys2.org/docs/ides-editors/#zed) first.
116
117## Troubleshooting
118
119### Setting `RUSTFLAGS` env var breaks builds
120
121If you set the `RUSTFLAGS` env var, it will override the `rustflags` settings in `.cargo/config.toml` which is required to properly build Zed.
122
123Since these settings can vary from time to time, the build errors you receive may vary from linker errors, to other stranger errors.
124
125If you'd like to add extra rust flags, you may do 1 of the following in `.cargo/config.toml`:
126
127Add your flags in the build section
128
129```toml
130[build]
131rustflags = ["-C", "symbol-mangling-version=v0", "--cfg", "tokio_unstable"]
132```
133
134Add your flags in the windows target section
135
136```toml
137[target.'cfg(target_os = "windows")']
138rustflags = [
139    "--cfg",
140    "windows_slim_errors",
141    "-C",
142    "target-feature=+crt-static",
143]
144```
145
146Or, 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`.
147
148```
149upper_dir
150├── .cargo          // <-- Make this folder
151│   └── config.toml // <-- Make this file
152└── zed
153    ├── .cargo
154    │   └── config.toml
155    └── crates
156        ├── assistant
157        └── ...
158```
159
160In the new (above) `.cargo/config.toml`, if we wanted to add `--cfg gles` to our rustflags, it would look like this
161
162```toml
163[target.'cfg(all())']
164rustflags = ["--cfg", "gles"]
165```
166
167### Cargo errors claiming that a dependency is using unstable features
168
169Try `cargo clean` and `cargo build`.
170
171### `STATUS_ACCESS_VIOLATION`
172
173This error can happen if you are using the "rust-lld.exe" linker. Consider trying a different linker.
174
175If 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.
176
177See this issue for more information [#12041](https://github.com/zed-industries/zed/issues/12041)
178
179### Invalid RC path selected
180
181Sometimes, depending on the security rules applied to your laptop, you may get the following error while compiling Zed:
182
183```
184error: failed to run custom build command for `zed(C:\Users\USER\src\zed\crates\zed)`
185
186Caused by:
187  process didn't exit successfully: `C:\Users\USER\src\zed\target\debug\build\zed-b24f1e9300107efc\build-script-build` (exit code: 1)
188  --- stdout
189  cargo:rerun-if-changed=../../.git/logs/HEAD
190  cargo:rustc-env=ZED_COMMIT_SHA=25e2e9c6727ba9b77415588cfa11fd969612adb7
191  cargo:rustc-link-arg=/stack:8388608
192  cargo:rerun-if-changed=resources/windows/app-icon.ico
193  package.metadata.winresource does not exist
194  Selected RC path: 'bin\x64\rc.exe'
195
196  --- stderr
197  The system cannot find the path specified. (os error 3)
198warning: build failed, waiting for other jobs to finish...
199```
200
201In 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:
202`C:\Program Files (x86)\Windows Kits\10\bin\<SDK_version>\x64`.
203
204See this [issue](https://github.com/zed-industries/zed/issues/18393) for more information.
205
206### Build fails: Path too long
207
208You may receive an error like the following when building
209
210```
211error: failed to get `pet` as a dependency of package `languages v0.1.0 (D:\a\zed-windows-builds\zed-windows-builds\crates\languages)`
212
213Caused by:
214  failed to load source for dependency `pet`
215
216Caused by:
217  Unable to update https://github.com/microsoft/python-environment-tools.git?rev=ffcbf3f28c46633abd5448a52b1f396c322e0d6c#ffcbf3f2
218
219Caused by:
220  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)
221```
222
223In order to solve this, you can enable longpath support for git and Windows.
224
225For git: `git config --system core.longpaths true`
226
227And for Windows with this PS command:
228
229```powershell
230New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
231```
232
233For more information on this, please see [win32 docs](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell)
234
235(note that you will need to restart your system after enabling longpath support)
236
237### Graphics issues
238
239#### Zed fails to launch
240
241Currently, 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.
242
243You can check the Zed log at:
244`C:\Users\YOU\AppData\Local\Zed\logs\Zed.log`
245
246If you see messages like:
247
248- `Zed failed to open a window: NoSupportedDeviceFound`
249- `ERROR_INITIALIZATION_FAILED`
250- `GPU Crashed`
251- `ERROR_SURFACE_LOST_KHR`
252
253Then Vulkan might not be working properly on your system. In most cases, updating your GPU drivers may help resolve this.
254
255If 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.