Setup your Keyman build environment on Windows

November 20, 2025 ยท View on GitHub

Target Projects

On Windows, you can build the following projects:

The following libraries can also be built:

  • Keyman Core (Windows, wasm targets)
  • Common libraries

The following projects cannot be built on Windows:

  • Keyman for Linux
  • Keyman for macOS
  • Keyman for iOS

System Requirements

  • Minimum Windows version: Windows 10 x64

Repository Paths

When cloning this repo for local development on a Windows machine, take care not to place it overly deep in your file system. Some of the paths for compilation can push character lengths around 160 characters long, while certain operations on Windows systems may be limited to paths of 260 characters or less. For example, git clean on Windows with msys is limited due to dependence on older Windows APIs.

Recommended filesystem layout:

C:\Projects\keyman\
  keyman\              this repository (https://github.com/keymanapp/keyman)
  keyboards\           https://github.com/keymanapp/keyboards
  lexical-models\      https://github.com/keymanapp/lexical-models
  CEF4Delphi_Binary\   https://github.com/keymanapp/CEF4Delphi_Binary
  sites\
    keyman.com\        https://github.com/keymanapp/keyman.com
    ...

Instructions and scripts in this file assume this layout; if you use a different layout, adjust the paths accordingly.

We recommend adding an exclusion for C:\Projects to your antivirus/security software, for performance reasons; this can also avoid build failures when security software locks generated executables to scan them, before the build has finished with them.

Project Requirements

Keyman for Windows

Dependencies:

Building:

Keyman Developer

Dependencies:

Building:

KeymanWeb

Dependencies:

Building:

Keyman for Android

Dependencies:

Building:

Dependencies and Prerequisites

Many dependencies are only required for specific projects.

We prefer Chocolatey at present for installation of most dependencies. Chocolatey should be run in an elevated PowerShell.

Base Dependencies

Projects:

  • all projects

Requirements:

  • git for Windows
  • jq
  • Python 3
  • Meson 1.0+
  • Ninja
  • Pandoc
# Elevated PowerShell
# for *much* faster download, hide progress bar (PowerShell/PowerShell#2138)
$ProgressPreference = 'SilentlyContinue'
choco install git jq python ninja pandoc meson

Environment variables:

If you pull the entire keyman.git repo to c:\keyman, then the paths by default will work without changes. Otherwise, you will need to set an environment variable KEYMAN_ROOT to the root path of the Keyman repo. For example:

SETX KEYMAN_ROOT "c:\Projects\keyman\keyman"

Note

The SETX command will set persistent environment variables but they do not impact the current shell environment. Start a new shell to see the variables.

Tip

To check whether environment variables are set, run SET <variable> in command prompt.

You can alternatively use Windows Settings to add these environment variables permanently:

  1. In Windows Search, type "environment" and select "Edit System Environment Variables"
  2. Click Environment Variables...
  3. You can add or edit variables in either User or System settings, as you prefer.

Web Dependencies

Projects:

  • Keyman Developer
  • Keyman for Android
  • KeymanWeb

Requirements:

  • node.js
  • Emscripten

node.js

Our recommended way to install node.js is to use nvm-windows. This makes it easy to switch between versions of node.js.

nvm install 20.16.0
nvm use 20.16.0

Emscripten

In bash, run the following commands:

cd /c/Projects/keyman
git clone https://github.com/emscripten-core/emsdk
cd emsdk
emsdk install 3.1.58
emsdk activate 3.1.58
cd upstream/emscripten
npm install

If you are updating an existing install of Emscripten:

cd emsdk
git pull
emsdk install 3.1.58
emsdk activate 3.1.58
cd upstream/emscripten
npm install

![WARNING] Emscripten very unhelpfully overwrites JAVA_HOME, and adds its own versions of Python, Node and Java to the PATH. For best results, restart your shell after installing Emscripten so that you don't end up with the wrong versions.

There is no need to add emscripten to the path in order to build Keyman. However, you should set the EMSCRIPTEN_BASE variable to the path where emcc can be found, in the upstream\emscripten subdirectory of where you installed emsdk.

Environment variables:

SETX EMSCRIPTEN_BASE "<your-emsdk-path>\upstream\emscripten"

Optional environment variables:

To let the Keyman build scripts control the version of Emscripten installed on your computer:

SETX KEYMAN_USE_EMSDK 1

Optional environment variables:

To let the Keyman build scripts control the version of node.js installed and active on your computer:

SETX KEYMAN_USE_NVM 1

See node.md for more information, including automatic selection of appropriate node versions during builds.

Windows Platform Dependencies

Projects:

  • Keyman Developer
  • Keyman for Windows

Requirements:

  • Delphi 10.3 Community or Professional: https://www.embarcadero.com/products/delphi/starter/free-download (Delphi Windows Community, DUnit Unit Testing Frameworks required)

    • Note: Delphi 10.3 Community is no longer available. Delphi 10.4 Community no longer includes command line compilers. This change means that building Keyman with Delphi 10.4 Community is not really viable. This means you can only really use the Professional Edition, which can be used on a trial basis for a short time. (We are actively working to remove Delphi dependencies given the licensing issues with using it.)

    Start Delphi IDE once after installation as it will create various environment files and take you through required registration.

    • Note: It is possible to build all components that do not require Delphi. Currently many components are Delphi-based, but if you are working just in Keyman Core, the compiler, or Keyman Engine's C++ components, you may be able to get away without building them. In this situation, we recommend copying the relevant Delphi-built components into windows/bin folders from a compatible installed version of Keyman for testing and debugging purposes.

  • Visual Studio 2022 Community (C++ native desktop workload)

    winget install --id=Microsoft.VisualStudio.2022.Community -e --override "--passive --add Microsoft.VisualStudio.Workload.NativeDesktop --add Microsoft.VisualStudio.Component.VC.Tools.ARM64 --add Microsoft.VisualStudio.Component.CppBuildInsights --add Microsoft.VisualStudio.Component.Debugger.JustInTime --add Microsoft.VisualStudio.Component.VC.ASAN --add Microsoft.VisualStudio.Component.VC.DiagnosticTools --add Microsoft.VisualStudio.Component.VC.TestAdapterForGoogleTest --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.Windows11SDK.26100 --add Microsoft.VisualStudio.Component.Windows11Sdk.WindowsPerformanceToolkit --add Microsoft.VisualStudio.Component.Windows10SDK.19041"

    • You can omit the --passive parameter to open the installer dialog and modify the selection before continuing with the install.

    • You can replace --passive with --quiet for a silent install (note that the winget command returns before the Visual Studio Installer finishes, so you won't be able to easily tell when installation completes; check Task Manager for setup.exe).

    • If you prefer to use the Visual Studio Installer instead of the command line install, then the following workloads and components should be included:

      • Visual Studio core editor
      • Desktop development with C++
        • C++ core desktop features
        • MSVC v143 - VS 2022 C++ x64/x86 build tools (latest)
        • C++ Build Insights
        • Just-In-Time debugger
        • C++ profiling tools
        • Test Adapter for Google Test
        • C++ AddressSanitizer
        • Windows 10 SDK (10.0.19041.0)
        • Windows 11 SDK (10.0.26100.6584)
      • Under individual components, add:
        • MSVC v143 - VS 2022 C++ ARM64/ARM64EC build tools (latest)

    Recommended: configure Visual Studio to use two-space tab stops:

    1. Open the options dialog: Tools > Options.
    2. Navigate to Text Editor > All Languages > Tabs.
    3. Change 'Tab size' to 2 and 'Indent size' to 2.
    4. Select 'Insert spaces'.

  • Windows SDK (C++ Desktop Development)

    This should be installed as a part of Visual Studio above

Required environment variables:

  • PATH
    • Add the C:\Projects\keyman\keyman\windows\lib folder in the Keyman repository to your PATH environment variable. This is required for Keyman's design-time packages to load in Delphi.

KEYMAN_CEF4DELPHI_ROOT

Keyman and Keyman Developer use Chromium Embedded Framework. The source repo is at https://github.com/keymanapp/CEF4Delphi. In order to build the installers, we need to source the binary files from the https://github.com/keymanapp/CEF4Delphi_binary repo. The KEYMAN_CEF4DELPHI_ROOT environment variable should be set to the root of this repo on your local machine.

The version of CEF in use is determined by CEF_VERSION.md. This maps to a branch prefixed with v e.g. v89.0.18 in the CEF4Delphi_binary repository. During a release build, the common/windows/cef-checkout.sh script will checkout the correct branch of the repository automatically and extract any compressed files found in it.

The KEYMAN_CEF4DELPHI_ROOT variable is used to specify the path to the CEF4Delphi binaries.

SETX KEYMAN_CEF4DELPHI_ROOT "c:\Projects\keyman\CEF4Delphi_Binary"

Additional requirements for release builds:

# Elevated PowerShell
choco install 7zip html-help-workshop
choco install wixtoolset --version=3.14.1
git clone https://github.com/keymanapp/CEF4Delphi_Binary C:\Projects\keyman\CEF4Delphi_Binary

Android dependencies

Projects:

  • Keyman for Android

Requirements:

  • Android SDK
  • Android Studio
  • Ant
  • Gradle
  • Maven
  • JDK 11 (Temurin11)

JDK 11

Use Powershell + Chocolatey to install JDK 11:

# Elevated PowerShell

# for *much* faster download, hide progress bar (PowerShell/PowerShell#2138)
$ProgressPreference = 'SilentlyContinue'
choco install temurin11

Multiple versions of Java: If you need to build Keyman for Android 16.0 or older versions, you can set JAVA_HOME_11 to the JDK 11 path and JAVA_HOME to the JDK 8 path. This will build both versions correctly from command line. But note that you do need to update your JAVA_HOME env var to the associated version before opening Android Studio and loading any Android projects. JAVA_HOME_11 is mostly used by CI.

Android Studio and friends

# Elevated PowerShell
choco install androidstudio ant gradle maven android-sdk

Start a new shell to get the new paths and then update Android SDKs:

# optionally install sdk images
sdkmanager --update
# sdkmanager "system-images;android-33;google_apis;armeabi-v7a"
sdkmanager --licenses
  • Run Android Studio once after installation to install additional components such as emulator images and SDK updates.

Certificates

In order to make a release build, you need to sign all the executables. See windows/src/README.md#Certificates for details on how to create test code signing certificates or specify your own certificates for the build.

Optional Tools

  • sentry-cli (optional)

    • Uploading symbols for Sentry-based error reporting

    bash:

    # bash
curl -sL https://sentry.io/get-cli/ | bash