1  # Windows / MSVC Build Guide
  2  
  3  This guide describes how to build bitcoind, command-line utilities, and GUI on Windows using Microsoft Visual Studio.
  4  
  5  For cross-compiling options, please see [`build-windows.md`](./build-windows.md).
  6  
  7  ## Preparation
  8  
  9  ### 1. Install Required Dependencies
 10  
 11  The first step is to install the required build applications. The instructions below use WinGet to install the applications.
 12  
 13  WinGet is available on all supported Windows versions. The applications mentioned can also be installed manually.
 14  
 15  #### Visual Studio
 16  
 17  This guide relies on using CMake and vcpkg package manager provided with the Visual Studio installation.
 18  
 19  Minimum required version: Visual Studio 2026 version 18.3 with the "Desktop development with C++" workload.
 20  
 21  To install Visual Studio Community Edition with the necessary components, run:
 22  
 23  ```powershell
 24  winget install --id Microsoft.VisualStudio.Community --override "--wait --quiet --add Microsoft.VisualStudio.Workload.NativeDesktop --add Microsoft.VisualStudio.Component.Git --includeRecommended"
 25  ```
 26  
 27  This installs:
 28  - Visual Studio
 29  - The "Desktop development with C++" workload (NativeDesktop)
 30  - Git component
 31  
 32  After installation, the commands in this guide should be executed in "Developer PowerShell for VS" or "Developer Command Prompt for VS".
 33  The former is assumed hereinafter.
 34  
 35  #### Python
 36  
 37  Python is required for running the test suite.
 38  
 39  To install Python, run:
 40  
 41  ```powershell
 42  winget install python3
 43  ```
 44  
 45  ### 2. Clone Bitcoin Repository
 46  
 47  `git` should already be installed as a component of Visual Studio. If not, download and install [Git for Windows](https://git-scm.com/downloads/win).
 48  
 49  Clone the Bitcoin Core repository to a directory. All build scripts and commands will run from this directory.
 50  
 51  ```powershell
 52  git clone https://github.com/bitcoin/bitcoin.git
 53  ```
 54  
 55  
 56  ## Triplets and Presets
 57  
 58  The Bitcoin Core project supports the following vcpkg triplets:
 59  - `x64-windows` (both CRT and library linkage is dynamic)
 60  - `x64-windows-static` (both CRT and library linkage is static)
 61  
 62  To facilitate build process, the Bitcoin Core project provides presets, which are used in this guide.
 63  
 64  Available presets can be listed as follows:
 65  ```powershell
 66  cmake --list-presets
 67  ```
 68  
 69  By default, all presets set `BUILD_GUI` to `ON`.
 70  
 71  ## Building
 72  
 73  CMake will put the resulting object files, libraries, and executables into a dedicated build directory.
 74  
 75  In the following instructions, the "Debug" configuration can be specified instead of the "Release" one.
 76  
 77  Run `cmake -B build -LH` to see the full list of available options.
 78  
 79  ### Building with Static Linking with GUI
 80  
 81  ```powershell
 82  cmake -B build --preset vs2026-static          # It might take a while if the vcpkg binary cache is unpopulated or invalidated.
 83  cmake --build build --config Release           # Append "-j N" for N parallel jobs.
 84  ctest --test-dir build --build-config Release  # Append "-j N" for N parallel tests.
 85  cmake --install build --config Release         # Optional.
 86  ```
 87  
 88  ### Building with Dynamic Linking without GUI
 89  
 90  ```powershell
 91  cmake -B build --preset vs2026 -DBUILD_GUI=OFF # It might take a while if the vcpkg binary cache is unpopulated or invalidated.
 92  cmake --build build --config Release           # Append "-j N" for N parallel jobs.
 93  ctest --test-dir build --build-config Release  # Append "-j N" for N parallel tests.
 94  ```
 95  
 96  ### vcpkg-specific Issues and Workarounds
 97  
 98  vcpkg installation during the configuration step might fail for various reasons unrelated to Bitcoin Core.
 99  
100  If the failure is due to a "Buildtrees path … is too long" error, which is often encountered when building
101  with `BUILD_GUI=ON` and using the default vcpkg installation provided by Visual Studio, you can
102  specify a shorter path to store intermediate build files by using
103  the [`--x-buildtrees-root`](https://learn.microsoft.com/en-us/vcpkg/commands/common-options#buildtrees-root) option:
104  
105  ```powershell
106  cmake -B build --preset vs2026-static -DVCPKG_INSTALL_OPTIONS="--x-buildtrees-root=C:\vcpkg"
107  ```
108  
109  If vcpkg installation fails with the message "Paths with embedded space may be handled incorrectly", which
110  can occur if your local Bitcoin Core repository path contains spaces, you can override the vcpkg install directory
111  by setting the [`VCPKG_INSTALLED_DIR`](https://github.com/microsoft/vcpkg-docs/blob/main/vcpkg/users/buildsystems/cmake-integration.md#vcpkg_installed_dir) variable:
112  
113  ```powershell
114  cmake -B build --preset vs2026-static -DVCPKG_INSTALLED_DIR="C:\path_without_spaces"
115  ```
116  
117  ## Performance Notes
118  
119  ### vcpkg Manifest Default Features
120  
121  One can skip vcpkg manifest default features to speed up the configuration step.
122  For example, the following invocation will skip all features except for "wallet" and "tests" and their dependencies:
123  ```powershell
124  cmake -B build --preset vs2026 -DVCPKG_MANIFEST_NO_DEFAULT_FEATURES=ON -DVCPKG_MANIFEST_FEATURES="wallet;tests" -DBUILD_GUI=OFF -DWITH_ZMQ=OFF
125  ```
126  
127  Available features are listed in the [`vcpkg.json`](/vcpkg.json) file.
128  
129  ### Antivirus Software
130  
131  To improve the build process performance, one might add the Bitcoin repository directory to the Microsoft Defender Antivirus exclusions.