How to Install Headlamp on Your Platform

Updated

Headlamp can be installed two ways: as a desktop app (Windows, Linux, macOS) for managing clusters locally without deploying anything in-cluster, or in-cluster as a web UI using Helm, kubectl, Minikube, Docker Desktop, or Glasskube. Pick the desktop route if you want to manage unrelated clusters from your machine; pick in-cluster if you want a shared web UI reachable by a team.

Desktop App Installation

Headlamp's desktop app suits users who don't want to deploy it in a cluster, or who want to manage unrelated clusters locally.

Windows

  • Download the binary directly, or install via a package manager:
    • WinGet: winget install headlamp
    • Chocolatey: choco install headlamp

Note: Windows may show warnings when running Headlamp as an unsigned app.

Linux

  • Download the binary directly, or install via Flatpak (make sure the Flathub repository is set up first):
    • flatpak install flathub io.kinvolk.Headlamp

macOS

  • Download the binary directly, or install via Homebrew:
    • brew install --cask headlamp

Note: macOS may show warnings when running Headlamp as an unsigned app.

In-Cluster Installation

A common use case for any Kubernetes web UI is to deploy it in-cluster and set up an ingress server so it's available to users. Headlamp supports several in-cluster install paths.

Helm

helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
helm install my-headlamp headlamp/headlamp --namespace kube-system

kubectl apply

Use a configuration file to set up a Headlamp deployment and service. Review it and change anything you need before applying:

kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/headlamp/main/kubernetes-headlamp.yaml

Minikube

minikube addons enable headlamp
minikube service headlamp -n headlamp

Docker Desktop

Headlamp ships as a Docker Desktop extension — install it from the Docker Desktop extensions catalog.

Glasskube

glasskube install headlamp

Choosing Between Desktop and In-Cluster

Consideration Desktop App In-Cluster
Where it runs Your local machine Your Kubernetes cluster
Best for Managing unrelated clusters locally; no in-cluster deployment Shared web UI for teams, with ingress
Install methods Binary, WinGet, Chocolatey, Flatpak, Homebrew Helm, kubectl apply, Minikube addon, Docker Desktop extension, Glasskube
Access model Local Web app reachable by users

Both forms can also be run together — Headlamp can run as a web app, a desktop app, or both.

What You Get Either Way

  • Adaptable UI & branding — create custom experiences with minimal effort.
  • RBAC-based controls — Headlamp adapts to a user's cluster permissions.
  • Kubernetes flavor compatibility — Headlamp works with your favorite Kubernetes flavor.

Headlamp is an official Kubernetes sub-project and part of SIG UI.