Windows (Visual Studio)

Building using Visual Studio

This guide sets up a KiCad development environment on 64-bit Windows 10 or 11 using Visual Studio, CMake presets, and vcpkg. It targets the master branch. The differences for the 10.0 stable branch are listed in Building the 10.0 stable branch.

Plan for about 60 GB of free disk space: 11 GB for Visual Studio, 5 GB for vcpkg, 4 GB for the source, and 40 GB for one Debug build.

The examples below use C:\dev\vcpkg for vcpkg and C:\dev\kicad for the KiCad source. Any location works, but short paths near the drive root avoid path length problems.

Install the tools

Visual Studio

Install Visual Studio 2022 or 2026. The free Community edition is sufficient. In the installer, select the Desktop development with C++ workload and keep its default components, which include C++ CMake tools for Windows.

To install Visual Studio 2026 from a terminal instead, run:

winget install --id Microsoft.VisualStudio.Community -e --override "--passive --wait --add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended"

For Visual Studio 2022, use the package ID Microsoft.VisualStudio.2022.Community. Restart Windows when the installer finishes.

KiCad’s continuous integration builds use Visual Studio 2022. Visual Studio 2026 also works and uses the same prebuilt dependencies.

Git

Install Git for Windows, or run:

winget install --id Git.Git -e

Enable long paths

Some dependency builds exceed the legacy 260 character path limit. Run the following once from an administrator PowerShell to lift the limit:

New-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled -Value 1 -PropertyType DWORD -Force

See Maximum Path Length Limitation for details.

Open a new terminal after installing these tools so that git is on your PATH.

Get the source code

git clone https://gitlab.com/kicad/code/kicad.git C:\dev\kicad

See Getting the KiCad Source Code for other ways to get the source.

Set up vcpkg

KiCad gets its dependencies from vcpkg in manifest mode. The dependency list is vcpkg.json in the KiCad source tree, and vcpkg-configuration.json adds KiCad’s own package registry on top of the standard one.

KiCad’s continuous integration publishes prebuilt dependencies to a public package feed. Using that feed saves building every dependency from source, but only if your vcpkg checkout matches the commit used by CI. That commit is the $vcpkgCommit value in build.ps1 in the kicad-win-builder repository.

Clone vcpkg, check out that commit, and bootstrap it:

git clone https://github.com/microsoft/vcpkg.git C:\dev\vcpkg
cd C:\dev\vcpkg
git checkout 66c0373dc7fca549e5803087b9487edfe3aca0a1  (1)
.\bootstrap-vcpkg.bat -disableMetrics
1 Replace this with the current $vcpkgCommit from build.ps1.

When CI moves to a new vcpkg commit, check out the new commit and run .\bootstrap-vcpkg.bat again.

Use your own vcpkg clone rather than the copy bundled with Visual Studio. The bundled copy follows the Visual Studio release, so it cannot be pinned to the CI commit, and it places the vcpkg build tree inside the KiCad build folder, where long paths cause build failures.

Configure CMake presets

KiCad ships a CMakePresets.json.sample file in the source root. Visual Studio and the command line both read their build settings from a CMakePresets.json file in the same place.

  1. Copy CMakePresets.json.sample to CMakePresets.json. Git ignores the copy, so your local edits stay out of commits.

  2. In the configure preset named msvc, replace the environment block and add VCPKG_OVERLAY_TRIPLETS to cacheVariables:

          "environment": {
        "VCPKG_ROOT": "C:/dev/vcpkg",
        "VCPKG_BINARY_SOURCES": "default;nuget,https://gitlab.com/api/v4/projects/27426693/packages/nuget/index.json,read"
      },
          "cacheVariables": {
        "KICAD_BUILD_QA_TESTS": "ON",
        "VCPKG_OVERLAY_TRIPLETS": "${sourceDir}/tools/custom_vcpkg_triplets"
      },

  3. If the sample contains a test preset named test-base without "hidden": true, add "hidden": true to it. Otherwise CMake rejects the file with Invalid preset: "test-base".

Each setting has a job:

VCPKG_ROOT

The location of your vcpkg clone. Use forward slashes.

VCPKG_BINARY_SOURCES

Tells vcpkg to check your local binary cache first (default) and then KiCad’s public package feed. vcpkg reads the feed directly. You do not need nuget.exe or a NuGet account.

VCPKG_OVERLAY_TRIPLETS

Selects KiCad’s x64-windows triplet, which leaves the compiler version out of the package hashes. Without it, a compiler that differs from the one CI used, even by a patch release, produces different hashes, and vcpkg rebuilds every dependency from source.

Both VCPKG_BINARY_SOURCES and VCPKG_OVERLAY_TRIPLETS are required for prebuilt packages. With either one missing, vcpkg reports Restored 0 package(s) and starts building everything.

Build in Visual Studio

  1. Start Visual Studio and choose Open a local folder. Select C:\dev\kicad.

  2. Visual Studio detects CMakePresets.json. Select Win64 Debug in the configuration drop-down on the toolbar.

  3. Visual Studio runs the CMake configure step, which installs the dependencies through vcpkg. Follow progress in the Output window (View > Output, then Show output from: CMake). Look for a line like Restored 143 package(s) from NuGet. The step is done when the output reads CMake generation finished.

  4. Choose Build > Build All.

If the output shows Building <package>:x64-windows lines instead of a restore, vcpkg is building dependencies from source. That takes much longer than a restore, and the output can stay silent for long stretches. Stop it and check the vcpkg commit and both preset settings above.

Build from the command line

The same presets work without the IDE. Open Developer PowerShell for VS from the Start menu so the compiler and the Visual Studio copies of CMake and Ninja are on your PATH, then run:

cd C:\dev\kicad
cmake --preset msvc-win64-debug
cmake --build --preset win64-debug

The build output goes to build\msvc-win64-debug. Use msvc-win64-release and win64-release for an optimized build with debug information.

Running and debugging

KiCad needs two things to run from the build folder:

KICAD_RUN_FROM_BUILD_DIR

Must be set (to any value). It tells KiCad to load its editors and data files from the build folder layout instead of an installed layout.

PATH

Must include the folders that hold KiCad’s shared libraries (common, api, and common\gal in the build folder) and the vcpkg debug\bin folder. vcpkg copies third-party DLLs next to each executable, but kicad.exe also loads editor modules from other folders, and those modules need the vcpkg folder to find their dependencies. Without it, the schematic editor fails to load.

Visual Studio reads these settings from .vs\launch.vs.json in the source root. To create the file, choose Debug > Debug and Launch Settings for kicad, then replace its contents with the following:

{
  "version": "0.2.1",
  "defaults": {},
  "configurations": [
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "kicad.exe (kicad\\kicad.exe)",
      "name": "kicad.exe (kicad\\kicad.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "eeschema.exe (eeschema\\eeschema.exe)",
      "name": "eeschema.exe (eeschema\\eeschema.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "pcbnew.exe (pcbnew\\pcbnew.exe)",
      "name": "pcbnew.exe (pcbnew\\pcbnew.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "gerbview.exe (gerbview\\gerbview.exe)",
      "name": "gerbview.exe (gerbview\\gerbview.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "pl_editor.exe (pagelayout_editor\\pl_editor.exe)",
      "name": "pl_editor.exe (pagelayout_editor\\pl_editor.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "pcb_calculator.exe (pcb_calculator\\pcb_calculator.exe)",
      "name": "pcb_calculator.exe (pcb_calculator\\pcb_calculator.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "bitmap2component.exe (bitmap2component\\bitmap2component.exe)",
      "name": "bitmap2component.exe (bitmap2component\\bitmap2component.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    }
  ]
}

Each program you want to start from Visual Studio needs its own entry. Select the program in the Select Startup Item drop-down on the toolbar, then press F5 to debug or Ctrl+F5 to run.

For a Release build, change x64-windows\\debug\\bin to x64-windows\\bin in each PATH.

To run KiCad from a terminal instead, set the same variables in Developer PowerShell for VS:

$b = "C:\dev\kicad\build\msvc-win64-debug"
$env:KICAD_RUN_FROM_BUILD_DIR = "1"
$env:PATH = "$b\vcpkg_installed\x64-windows\debug\bin;$b\common;$b\api;$b\common\gal;$env:PATH"
& "$b\kicad\kicad.exe"

Running the tests

The presets build KiCad’s QA tests (KICAD_BUILD_QA_TESTS). The command line tests in qa_cli use pytest, which must be installed into the Python that vcpkg provides. Do this once per build folder:

cmake --build --preset win64-debug --target qa_python_deps

Then run the tests from Developer PowerShell for VS:

ctest --preset win64-debug

The test preset stops at the first failing test. To run every test and see the output of each failure, call ctest on the build folder directly:

ctest --test-dir build\msvc-win64-debug --output-on-failure

Building the 10.0 stable branch

The 10.0 branch still includes the SWIG-based Python scripting interface. Everything above applies, with two additions described below. To switch an existing clone to the branch, run git checkout 10.0, or add a separate worktree with git worktree add C:\dev\kicad-10 10.0.

SWIG

Download swigwin from SourceForge and extract it, for example to C:\dev\swigwin-4.3.1. Use the version named by $swigwinFolder in build.ps1. Then add its path to cacheVariables in the msvc preset:

        "SWIG_EXECUTABLE": "C:/dev/swigwin-4.3.1/swig.exe"
The SWIG.SWIG winget package does not work. Its swig command reports a library folder that does not exist, and CMake fails with Could NOT find SWIG (missing: SWIG_DIR).

Python environment

When run from the build folder, KiCad 10.0 needs to be told where Python is. Add these entries to the env section of each configuration in launch.vs.json:

        "KICAD_USE_EXTERNAL_PYTHONHOME": "1",
        "PYTHONHOME": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\tools\\python3",
        "PYTHONPATH": "${cmake.buildRoot}\\pcbnew;${projectDir}\\scripting",

KICAD_USE_EXTERNAL_PYTHONHOME tells KiCad to honor PYTHONHOME instead of the location an installed copy of KiCad uses. PYTHONHOME points at the Python that vcpkg installs. PYTHONPATH finds the pcbnew Python module, which is built next to pcbnew.exe, and the kicad_pyshell module in the source tree.

Visual Studio extras

Formatting

KiCad’s _clang-format file sits in the source root. Visual Studio uses it automatically for Edit > Advanced > Format Document (Ctrl+K, Ctrl+D) and Format Selection. Format only the lines you change. See the code style guide.

The Trailing Whitespace Visualizer extension highlights trailing whitespace and removes it on save.

natvis definitions for libraries

Visual Studio can use natvis files to display library types in a readable form while debugging. These are useful for KiCad:

Download them into the Visualizers folder inside your Visual Studio folder in Documents, for example %USERPROFILE%\Documents\Visual Studio 2022\Visualizers. Create the folder if it does not exist. Visual Studio loads the files at startup.

Advanced

Try these changes only after the basic setup above works.

Binary cache location

vcpkg stores every dependency it builds from source in a local binary cache, usually %LOCALAPPDATA%\vcpkg\archives. Packages restored from KiCad’s feed are downloaded again when needed and are not stored there. The cache lets vcpkg reinstall locally built dependencies in seconds after you delete a build folder or switch branches. It grows over time.

To move the cache, set the environment variable VCPKG_DEFAULT_BINARY_CACHE to another folder. You can delete old files in the cache at any time. vcpkg restores or rebuilds whatever it needs.

Disabling manifest mode

In manifest mode, CMake installs the dependencies that match the checked-out KiCad commit every time it configures. This keeps your dependencies correct, but each build folder carries its own copy of the dependencies, and moving between distant commits can trigger reinstalls.

To manage the dependencies yourself instead:

  1. Copy vcpkg-configuration.json from the KiCad source root to the vcpkg root.

  2. Run vcpkg install from the vcpkg root for every package in KiCad’s vcpkg.json, including its features, with --triplet x64-windows and the same --overlay-triplets folder as above.

  3. Add "VCPKG_MANIFEST_MODE": "OFF" to cacheVariables in your preset.

  4. Point the PATH entries in launch.vs.json at C:\dev\vcpkg\installed\x64-windows\debug\bin instead of the build folder.

  5. Delete the CMake cache and configure again.

With manifest mode off, you must keep your installed packages in line with vcpkg.json yourself. Check it whenever you pull changes.

Troubleshooting

Invalid preset: "test-base"

Add "hidden": true to the test-base entry under testPresets in your CMakePresets.json.

vcpkg builds every dependency from source

The log shows Restored 0 package(s) followed by Building …​ lines. Check that:

  • vcpkg is checked out at the current $vcpkgCommit and you ran bootstrap-vcpkg.bat afterwards,

  • VCPKG_BINARY_SOURCES contains the KiCad feed URL, and

  • VCPKG_OVERLAY_TRIPLETS points at tools/custom_vcpkg_triplets in the KiCad source.

After fixing the settings, use Project > Delete Cache and Reconfigure in Visual Studio, or delete the build folder before configuring again from the command line.

When a KiCad commit changes vcpkg.json, the feed has the new packages only after CI has built that commit.

vcpkg cannot finish installing a dependency

Antivirus software is known to block steps in package builds. Add an exclusion for the vcpkg and KiCad folders, or pause real-time protection while dependencies build. On Windows 11, placing the source and vcpkg on a Dev Drive also reduces antivirus overhead during builds.

Couldn’t find the versions database file

vcpkg and the registries fell out of step with the packages already installed in the build folder. Use Project > Delete Cache and Reconfigure, or delete the build folder and configure again.

Last Modified