Install KXBuild manually

Use these steps if the one-line installer doesn't work in your environment, you want to choose each component's version and location, or you're installing on an offline network. You end up with exactly what the script installs.

Back to the one-line installer

What gets installed

Every component lives under one install root, called KXBUILD_HOME below. It defaults to %USERPROFILE%\kxbuild on Windows and ~/kxbuild on Linux and macOS. You can pick another folder, but then adjust every step to match.

Component	Purpose	Location	Installed by
kxbuild	The main CLI. It drives every other component.	KXBUILD_HOME/bin/	You
C++ build tools	Needed to compile with the Swift toolchain and to build CocoaPods' native extensions	Windows: Visual Studio C++ Build Tools. Linux: gcc, make and other system packages. macOS: Xcode Command Line Tools.	You
Ruby + CocoaPods	Dependency management for iOS projects	KXBUILD_HOME/ruby/, or an existing system install	On Windows, you install Ruby and doctor installs CocoaPods. On Linux and macOS, you install both.
Node.js ≥ 20	Only needed for React Native and Expo projects	KXBUILD_HOME/node/, or an existing system install	You
Swift toolchain	Compiles Swift and Objective-C code. Its version must match the one the iOS SDK requires.	KXBUILD_HOME/Developer/Toolchains/ (on a Mac with Xcode, Xcode's toolchain is used)	You
iOS SDK and other components	The iPhoneOS SDK plus tools such as xcrun, ld64.lld and clang	KXBUILD_HOME/Developer/Platforms/ and nearby folders	kxbuild doctor

The Swift version must be : it is the version the iOS SDK that doctor downloads in the last step was built with, and the two have to match exactly. doctor installs Apple's toolchain libraries along with the SDK, so nothing else is needed for them. If the download fails, iOS SDK explains how to put the SDK in place by hand.

Windows limits paths to 260 characters by default, so don't nest KXBUILD_HOME too deeply. The commands below assume the default %USERPROFILE%\kxbuild. Run every PowerShell command in an Administrator window.

Visual Studio C++ Build Tools + Windows SDK

On Windows, Swift compiles with MSVC and links against the Windows SDK, so install these first. Download them from the Visual Studio website and select "Desktop development with C++", or run:

PS> winget install --id Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --norestart --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

This takes 10-20 GB of disk space. If you already have Visual Studio, open the Visual Studio Installer and add the "Desktop development with C++" workload.

Download kxbuild

Download the archive for your architecture and put the kxbuild.exe inside it in %USERPROFILE%\kxbuild\bin\:

Windows x64 Windows ARM64

PS> New-Item -ItemType Directory -Force "$env:USERPROFILE\kxbuild\bin" | Out-Null
PS> Expand-Archive -Force "$env:USERPROFILE\Downloads\kxbuild.zip" "$env:TEMP\kxbuild"
PS> Move-Item -Force (Get-ChildItem "$env:TEMP\kxbuild" -Recurse -Filter kxbuild.exe)[0].FullName "$env:USERPROFILE\kxbuild\bin\kxbuild.exe"

The downloaded file name may include a version number, so change kxbuild.zip in the command to match. The links always point to the latest release, and the exact version doesn't matter because kxbuild doctor updates kxbuild automatically once it's installed.

Ruby + DevKit

CocoaPods is a Ruby gem with native extensions, so you need the version with DevKit. Download "Ruby+Devkit 3.4.x (x64)" from rubyinstaller.org, install it to %USERPROFILE%\kxbuild\ruby, then run this in PowerShell:

PS> & "$env:USERPROFILE\kxbuild\ruby\bin\ridk.cmd" install 1 3

ridk install 1 3 installs the MSYS2 base system and the MinGW build toolchain, a few hundred MB. Skip this step if you already have a Ruby with ridk. kxbuild doctor installs CocoaPods itself.

Node.js ≥ 20

Only React Native and Expo projects need this. If you already have node v20 or later, skip it. Otherwise download the LTS .zip (not the .msi) from nodejs.org and extract its contents to:

%USERPROFILE%\kxbuild\node\ (node.exe sits directly in this folder)

The .zip keeps your existing node untouched. If a global install is fine with you, run the .msi instead and leave node out of PATH in step 6.

Swift toolchain

Download the version the SDK requires (see the top of this page) from swift.org. Install it to %USERPROFILE%\kxbuild\Developer with only the NoAsserts toolchain:

PS> & "$env:USERPROFILE\Downloads\swift--RELEASE-windows10.exe" /quiet /norestart InstallRoot="$env:USERPROFILE\kxbuild\Developer" OptionsInstallAssertsToolchain=0 OptionsInstallNoAssertsToolchain=1

The download is about 1.7 GB and takes about 4.5 GB once installed. On ARM64, replace windows10 in the file name with windows10-arm64. The default +Asserts toolchain runs compiler self-checks on every build, which only slows things down, so use NoAsserts.

Environment variables

Set the user environment variable KXBUILD_HOME and prepend bin, node and ruby\bin to PATH:

PS> [Environment]::SetEnvironmentVariable('KXBUILD_HOME', "$env:USERPROFILE\kxbuild", 'User')
PS> [Environment]::SetEnvironmentVariable('PATH', "$env:USERPROFILE\kxbuild\bin;$env:USERPROFILE\kxbuild\node;$env:USERPROFILE\kxbuild\ruby\bin;" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')

If you use an existing node or ruby, remove its entry from PATH. The changes take effect in a new terminal.

Run kxbuild doctor to install the rest

Open a new Administrator PowerShell and run:

PS> kxbuild doctor

doctor checks each of the steps above, then installs the iOS SDK from sharedcomponents and downloads CocoaPods and the remaining tools through kpm. It also turns on Windows Developer Mode and long path support, which is why it needs Administrator rights. If any step went wrong, doctor tells you which one.

The examples below assume x86_64 and ~/kxbuild. On Ubuntu in WSL, follow the Linux steps exactly. Don't use the Windows node (/mnt/c/...), because it can't run Linux tools.

Build packages

Install gcc, make, cmake and other basic tools, plus the shared libraries the Swift toolchain needs. On Debian or Ubuntu:

$ sudo apt-get update && sudo apt-get install -y build-essential cmake rsync zip unzip git binutils gnupg2 libc6-dev libcurl4-openssl-dev libedit2 libpython3-dev libsqlite3-0 libxml2-dev libncurses-dev libz3-dev pkg-config tzdata zlib1g-dev

On Fedora or RHEL:

$ sudo dnf install -y gcc gcc-c++ make cmake rsync zip unzip git binutils libcurl-devel libedit-devel libicu-devel sqlite-devel python3-devel libuuid-devel libxml2-devel zlib-devel

For other distributions, install the dependencies listed on swift.org's Linux install page.

Download kxbuild

Download the archive and put the kxbuild inside it in ~/kxbuild/bin/. On arm64, change amd64 in the URL to arm64.

$ mkdir -p ~/kxbuild/bin /tmp/kxbuild
$ curl -fsSL -o /tmp/kxbuild.zip "https://kpm.kxbuild.net/latest/kxbuild/kxbuild?platform=linux&arch=amd64"
$ unzip -oq /tmp/kxbuild.zip -d /tmp/kxbuild
$ install -m 755 "$(find /tmp/kxbuild -type f -name kxbuild | head -n 1)" ~/kxbuild/bin/kxbuild

The link always points to the latest release, and kxbuild doctor keeps kxbuild up to date once it's installed.

Ruby + CocoaPods

The simplest option is to install CocoaPods globally with your distribution's Ruby:

$ sudo apt-get install -y ruby-full && sudo gem install cocoapods --no-document

To leave the system Ruby alone, do what the one-line installer does. Extract portable-ruby to ~/kxbuild/ruby, install CocoaPods with GEM_HOME=~/kxbuild/ruby/gems, then write a wrapper script at ~/kxbuild/bin/pod that sets GEM_HOME and calls ruby gems/bin/pod. All that matters is that pod is on your PATH.

Node.js ≥ 20

Only React Native and Expo projects need this. If node -v already shows v20 or later, skip it. Otherwise extract the LTS build from nodejs.org to ~/kxbuild/node, replacing the version with the current LTS:

$ mkdir -p ~/kxbuild/node && curl -fsSL https://nodejs.org/dist/v24.21.0/node-v24.21.0-linux-x64.tar.gz | tar -xz -C ~/kxbuild/node --strip-components=1

Swift toolchain

Install it with swiftly, the official toolchain manager from swift.org, and keep both swiftly and the toolchain in ~/kxbuild. kxbuild scans the Developer/Toolchains folder.

$ export SWIFTLY_HOME_DIR=~/kxbuild/swiftly SWIFTLY_BIN_DIR=~/kxbuild/swiftly/bin SWIFTLY_TOOLCHAINS_DIR=~/kxbuild/Developer/Toolchains
$ mkdir -p "$SWIFTLY_BIN_DIR" "$SWIFTLY_TOOLCHAINS_DIR" /tmp/swiftly
$ curl -fsSL "https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz" | tar -xz -C /tmp/swiftly
$ /tmp/swiftly/swiftly init --assume-yes --skip-install --no-modify-profile
$ "$SWIFTLY_BIN_DIR/swiftly" install  --use --assume-yes

The toolchain is about 1 GB. If swiftly reports missing system libraries afterwards, install them with the sudo command it prints.

Environment variables

Save the following as ~/kxbuild/env.sh:

export KXBUILD_HOME="$HOME/kxbuild"
export SWIFTLY_HOME_DIR="$KXBUILD_HOME/swiftly"
export SWIFTLY_BIN_DIR="$KXBUILD_HOME/swiftly/bin"
export SWIFTLY_TOOLCHAINS_DIR="$KXBUILD_HOME/Developer/Toolchains"
export PATH="$KXBUILD_HOME/node/bin:$KXBUILD_HOME/bin:$SWIFTLY_BIN_DIR:$KXBUILD_HOME/ruby/bin:$PATH"

Then load it when your shell starts (use ~/.zshrc for zsh):

$ printf '\n# kxbuild\n. "$HOME/kxbuild/env.sh"\n' >> ~/.bashrc && . ~/kxbuild/env.sh

If you use the system node or ruby, remove that folder from PATH. Leaving in a folder that doesn't exist is harmless too.

Run kxbuild doctor to install the rest

$ kxbuild doctor

doctor checks each of the steps above, then installs the iOS SDK from sharedcomponents and downloads the remaining components through kpm. If any step went wrong, doctor tells you which one.

On a Mac with full Xcode installed, kxbuild uses Xcode's Swift toolchain, so skip step 5. The examples below assume Apple silicon and ~/kxbuild.

Xcode Command Line Tools

Without Xcode, you need at least the Command Line Tools, which include clang, git and make:

$ xcode-select --install

A system dialog opens. Finish the installation there before you continue.

Download kxbuild

Download the archive and put the kxbuild inside it in ~/kxbuild/bin/. On an Intel Mac, change arm64 in the URL to amd64.

$ mkdir -p ~/kxbuild/bin /tmp/kxbuild
$ curl -fsSL -o /tmp/kxbuild.zip "https://kpm.kxbuild.net/latest/kxbuild/kxbuild?platform=darwin&arch=arm64"
$ unzip -oq /tmp/kxbuild.zip -d /tmp/kxbuild
$ install -m 755 "$(find /tmp/kxbuild -type f -name kxbuild | head -n 1)" ~/kxbuild/bin/kxbuild

The link always points to the latest release, and kxbuild doctor keeps kxbuild up to date once it's installed.

CocoaPods

If you have Homebrew:

$ brew install cocoapods

Without Homebrew, use the system Ruby with sudo gem install cocoapods, or put portable-ruby in ~/kxbuild/ruby as described on the Linux tab. All that matters is that pod is on your PATH.

Node.js ≥ 20

Only React Native and Expo projects need this. If node -v already shows v20 or later, skip it. Otherwise run:

$ brew install node

You can also install the LTS .pkg from nodejs.org. To keep node in ~/kxbuild/node, extract the darwin-arm64 archive with tar as shown on the Linux tab.

Swift toolchain (without Xcode)

Install the version the SDK requires with swiftly, and put the toolchain in ~/kxbuild/Developer/Toolchains:

$ export SWIFTLY_HOME_DIR=~/kxbuild/swiftly SWIFTLY_BIN_DIR=~/kxbuild/swiftly/bin SWIFTLY_TOOLCHAINS_DIR=~/kxbuild/Developer/Toolchains
$ mkdir -p "$SWIFTLY_BIN_DIR" "$SWIFTLY_TOOLCHAINS_DIR"
$ curl -fsSL -o /tmp/swiftly.pkg https://download.swift.org/swiftly/darwin/swiftly.pkg
$ installer -pkg /tmp/swiftly.pkg -target CurrentUserHomeDirectory
$ ~/.swiftly/bin/swiftly init --assume-yes --skip-install --no-modify-profile
$ "$SWIFTLY_BIN_DIR/swiftly" install  --use --assume-yes

The toolchain is about 1 GB.

Environment variables

Save the following as ~/kxbuild/env.sh. Put bin at the end of PATH, because the system xcrun and codesign must take precedence over kxbuild's stand-ins of the same name.

export KXBUILD_HOME="$HOME/kxbuild"
export SWIFTLY_HOME_DIR="$KXBUILD_HOME/swiftly"
export SWIFTLY_BIN_DIR="$KXBUILD_HOME/swiftly/bin"
export SWIFTLY_TOOLCHAINS_DIR="$KXBUILD_HOME/Developer/Toolchains"
export PATH="$KXBUILD_HOME/node/bin:$PATH:$KXBUILD_HOME/bin:$SWIFTLY_BIN_DIR:$KXBUILD_HOME/ruby/bin"

Then load it when your shell starts:

$ printf '\n# kxbuild\n. "$HOME/kxbuild/env.sh"\n' >> ~/.zprofile && . ~/kxbuild/env.sh

Run kxbuild doctor to install the rest

$ kxbuild doctor

doctor checks each of the steps above, then installs the iOS SDK from sharedcomponents and downloads the remaining components through kpm. If any step went wrong, doctor tells you which one.

Stuck during installation? Run kxbuild doctor first and see what it reports. If that doesn't help, email admin@kxbuild.net with the doctor output.