Documentation Index
Fetch the complete documentation index at: https://mintlify.com/KiCad/kicad-source-mirror/llms.txt
Use this file to discover all available pages before exploring further.
This guide covers building KiCad from source on various platforms using CMake.
Prerequisites
Required Dependencies
KiCad requires the following libraries and tools:
- CMake 3.22 or higher (3.28.1+ for MSVC ARM builds)
- C++20 compiler
- GCC (Linux)
- Clang (macOS/Linux)
- MSVC (Windows)
- SWIG 4.0 or higher (for Python scripting)
Core Libraries
- wxWidgets 3.2.0 or higher (gl, aui, adv, html, core, net, base, propgrid, xml, stc, richtext, webview)
- Boost 1.71.0 or higher (locale, unit_test_framework for QA)
- OpenGL with GLU
- GLM 0.9.8 or higher
- Cairo 1.12 or higher
- Pixman 0.30 or higher
Additional Libraries
- Python 3.6 or higher (interpreter and libraries)
- libgit2 1.5 or higher
- CURL
- ZLIB
- Zstd
- ngspice (for circuit simulator)
- OpenCASCADE 7.5.0 or higher (for STEP support)
- Protobuf (for IPC API)
- Freetype 2.11.1+ on MSVC
- HarfBuzz (font support)
- Fontconfig (font support)
- Linux: GTK3, libspnav (3D mouse), Wayland 1.20+ (optional)
- Windows: Windows SDK
- macOS: Xcode Command Line Tools
Quick Start
Basic Build Commands
# Clone the repository
git clone https://gitlab.com/kicad/code/kicad.git
cd kicad
# Create build directory
mkdir -p build/release
cd build/release
# Configure
cmake ../.. -DCMAKE_BUILD_TYPE=Release
# Build (use -j<N> for parallel builds)
make -j$(nproc)
# Install (optional)
sudo make install
Important CMake Options
Build Type
-DCMAKE_BUILD_TYPE=<type>
Release - Optimized build (default)Debug - Debug symbols, no optimizationRelWithDebInfo - Release with debug infoQABuild - Custom QA build without NDEBUG
Installation Prefix
-DCMAKE_INSTALL_PREFIX=/usr/local # Default
Feature Flags
Python Scripting
-DKICAD_SCRIPTING_WXPYTHON=ON # Build wxPython support (default: ON)
Testing and QA
-DKICAD_BUILD_QA_TESTS=ON # Build QA tests (default: ON)
-DKICAD_SPICE_QA=ON # Build spice QA tests (default: ON)
Optional Features
-DKICAD_SIGNAL_INTEGRITY=ON # Signal integrity tools (default: ON)
-DKICAD_IPC_API=ON # IPC API support (default: ON)
-DKICAD_UPDATE_CHECK=ON # Update checking (default: ON)
-DKICAD_USE_SENTRY=OFF # Sentry metrics (default: OFF)
-DKICAD_BUILD_I18N=OFF # Build translations (default: OFF)
# Linux
-DKICAD_WAYLAND=ON # Wayland support (default: ON on Linux)
-DKICAD_BUILD_FLATPAK=OFF # Flatpak conventions (default: OFF)
# Windows
-DKICAD_WIN32_DPI_AWARE=OFF # DPI awareness (default: OFF)
-DKICAD_WIN32_BUILD_PARALLEL_CL_MP=OFF # Parallel /MP compilation
-DKICAD_WIN32_LTCG=OFF # Link-time code generation
# macOS
-DKICAD_APPLE_MAKE_RELOCATEABLE_BUNDLE=ON # Relocatable bundle
Debugging and Development
# Sanitizers (not compatible with gold linker)
-DKICAD_SANITIZE_ADDRESS=OFF # Address sanitizer
-DKICAD_SANITIZE_THREADS=OFF # Thread sanitizer
# Debug options
-DKICAD_STDLIB_DEBUG=OFF # libstdc++ debug mode
-DKICAD_STDLIB_LIGHT_DEBUG=OFF # Lightweight debug assertions
-DKICAD_USE_VALGRIND=OFF # Valgrind instrumentation
-DKICAD_BUILD_SMALL_DEBUG_FILES=OFF # Smaller debug binaries (Linux)
# Profiling
-DKICAD_GAL_PROFILE=OFF # GAL profiling
# Development tools
-DKICAD_DRC_PROTO=OFF # DRC prototype tool
-DKICAD_BUILD_PNS_DEBUG_TOOL=OFF # P&S debug tool
Compiler Options
-DCMAKE_CXX_FLAGS="<flags>" # Extra C++ compiler flags
-DCMAKE_VERBOSE_MAKEFILE=ON # Verbose build output
-DUSE_CCACHE=ON # Use ccache for faster rebuilds
-DUSE_DISTCC=ON # Use distcc for distributed builds
-DKICAD_USE_PCH=ON # Precompiled headers (default: ON)
Variable Initialization
-DKICAD_INIT_VARIABLES=Default # Options: Default, Off, Zero, Pattern
Installation Locations
Linux
Default locations (with CMAKE_INSTALL_PREFIX=/usr/local):
/usr/local/bin - Binaries
/usr/local/lib/kicad - Shared libraries
/usr/local/share/kicad - Data files
/usr/local/share/kicad/demos - Demo projects
/usr/local/share/kicad/template - Project templates
/usr/local/share/doc/kicad - Documentation
macOS
Application bundle structure:
KiCad.app/
├── Contents/
│ ├── MacOS/ - Executables
│ ├── Frameworks/ - Shared libraries
│ ├── PlugIns/ - KiFace modules
│ └── SharedSupport/ - Data files
Windows
C:\Program Files\KiCad\
├── bin\ - Binaries and DLLs
├── share\kicad\ - Data files
└── share\doc\kicad\ - Documentation
Build Examples
Development Build
cmake ../.. \
-DCMAKE_BUILD_TYPE=Debug \
-DKICAD_BUILD_QA_TESTS=ON \
-DKICAD_STDLIB_LIGHT_DEBUG=ON \
-DUSE_CCACHE=ON
Release Build
cmake ../.. \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr/local \
-DKICAD_BUILD_QA_TESTS=OFF
Minimal Build (No Python)
cmake ../.. \
-DCMAKE_BUILD_TYPE=Release \
-DKICAD_SCRIPTING_WXPYTHON=OFF
Troubleshooting
Missing Dependencies
If CMake reports missing packages, install the development packages for your distribution:
Ubuntu/Debian:
sudo apt-get install cmake build-essential libwxgtk3.2-dev \
libboost-dev libboost-locale-dev python3-dev swig libglm-dev \
libcairo2-dev libpixman-1-dev libgit2-dev libcurl4-openssl-dev \
zlib1g-dev libzstd-dev libngspice0-dev libocct-dev
sudo dnf install cmake gcc-c++ wxGTK-devel boost-devel python3-devel \
swig glm-devel cairo-devel pixman-devel libgit2-devel libcurl-devel \
zlib-devel libzstd-devel ngspice-devel opencascade-devel
Build Errors
- Out of memory: Reduce parallel jobs (
make -j2 instead of make -j$(nproc))
- Compiler version: Ensure you have a C++20 compatible compiler
- wxWidgets version mismatch: Ensure wxWidgets and wxPython use the same version/toolkit
Advanced Topics
Cross-Compilation
For cross-compilation, set the appropriate CMake toolchain file:
cmake ../.. -DCMAKE_TOOLCHAIN_FILE=<toolchain-file>
Custom Python Site Packages
-DPYTHON_SITE_PACKAGE_PATH=/custom/path
Link Maps (Linux only)
-DKICAD_MAKE_LINK_MAPS=ON
Next Steps
After successfully building KiCad:
- Run the test suite:
ctest --output-on-failure
- Review the code style guidelines
- Start making changes and submit merge requests