Installation

This guide will help you install k0da on your system.

Installation Methods

Method 1: Download Pre-built Binaries (Recommended)

Download the latest release from GitHub:

# Download for Linux (AMD64)
curl -LO https://github.com/makhov/k0da/releases/latest/download/k0da-linux-amd64

# Download for macOS (ARM64)
curl -LO https://github.com/makhov/k0da/releases/latest/download/k0da-darwin-arm64

# Download for macOS (AMD64)
curl -LO https://github.com/makhov/k0da/releases/latest/download/k0da-darwin-amd64

# Download for Windows
curl -LO https://github.com/makhov/k0da/releases/latest/download/k0da-windows-amd64.exe

Make it executable and move to your PATH:

# Linux/macOS
chmod +x k0da-*
sudo mv k0da-* /usr/local/bin/k0da

# Verify installation
k0da version

Method 2: Build from Source

If you prefer to build from source or want the latest development version:

# Clone the repository
git clone https://github.com/makhov/k0da.git
cd k0da

# Build the binary
make build

# Install to /usr/local/bin (optional)
sudo mv k0da-* /usr/local/bin/k0da

Method 3: Using Go Install

Install directly using Go:

go install github.com/makhov/k0da@latest

Note

Make sure your $GOPATH/bin is in your $PATH to use k0da directly.

Verify Installation

After installation, verify that k0da is working correctly:

# Check version
k0da version

# Check available commands
k0da --help

You should see output similar to:

k0da version v1.0.0
commit: abc123def
built: 2024-01-15T10:30:00Z
go version: go1.27.0

Container Runtime Setup

Docker

Install Docker following the official Docker installation guide.

Test your Docker installation:

docker run hello-world

Podman

Install Podman following the official Podman installation guide.

Rootless Podman is supported. k0da detects a rootless runtime and configures the node for it automatically: the kubelet is started with --feature-gates=KubeletInUserNamespace=true so it tolerates running in a user namespace, and a containerd drop-in sets restrict_oom_score_adj = true so runc does not try to lower oom_score_adj, which a user namespace forbids. Without these the kubelet crash-loops on /dev/kmsg and every pod sandbox fails.

If you pass your own --kubelet-extra-args, k0da leaves it alone — include --feature-gates=KubeletInUserNamespace=true yourself or the kubelet will not start.

A rootful machine also works if you prefer one:

podman machine set --rootful
podman machine stop
podman machine start

Test your Podman installation:

podman run hello-world

kubectl Installation

Install kubectl to interact with your k0da clusters:

# macOS (using Homebrew)
brew install kubectl

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

# Windows (using Chocolatey)
choco install kubernetes-cli

Verify kubectl installation:

kubectl version --client

Next Steps

Now that you have k0da installed, proceed to the Quick Start Guide to create your first cluster!

Troubleshooting

Common Issues

"k0da: command not found"

Ensure the k0da binary is in your PATH. Check with:

echo $PATH
which k0da

Docker/Podman Permission Issues

Ensure your user is in the docker group (Linux) or Docker Desktop is running (macOS/Windows):

# Linux: Add user to docker group
sudo usermod -aG docker $USER
# Log out and log back in

Go Build Issues

Ensure you have Go 1.27+ installed:

go version

If you need to update Go, download it from golang.org.

For more help, check the CLI Reference or create an issue on GitHub.