Installation

KubeGraf is distributed as a single binary with no dependencies. Choose your preferred installation method below.

Prerequisites: You need a working kubectl configuration with access to a Kubernetes cluster.

Watch: Install KubeGraf in 5 Minutes

From download to a running dashboard with your cluster connected.

Installation Methods at a Glance

macOS

  • Homebrew (recommended)
  • Manual download (Apple Silicon or Intel)
  • Quick install script

Linux

  • Manual download (amd64 or arm64)
  • Quick install script
  • Works on all distros

Windows

  • GUI installer (recommended)
  • Scoop package manager
  • Manual ZIP download

Quick Install

The fastest way to install KubeGraf on macOS or Linux:

curl -sSL https://kubegraf.io/install.sh | bash

This script automatically detects your OS and architecture, downloads the appropriate binary, and installs it to /usr/local/bin.

macOS

Homebrew Recommended

The easiest way to install KubeGraf on macOS:

brew tap kubegraf/tap
brew install kubegraf

To upgrade: brew upgrade kubegraf

Apple Silicon (M1/M2/M3/M4)

For Macs with Apple silicon processors (2020+):

VERSION=$(curl -s https://api.github.com/repos/kubegraf/kubegraf/releases/latest | grep '"tag_name"' | cut -d'"' -f4)
curl -LO "https://github.com/kubegraf/kubegraf/releases/download/${VERSION}/kubegraf-${VERSION#v}-darwin-arm64.tar.gz"
tar xzf "kubegraf-${VERSION#v}-darwin-arm64.tar.gz" && sudo mv kubegraf /usr/local/bin/

Note: You can verify your chip type by clicking the Apple menu () → About This Mac. If it says "Chip: Apple M1/M2/M3/M4", you have Apple Silicon.

Intel Processor

For Macs with Intel processors (typically pre-2020):

VERSION=$(curl -s https://api.github.com/repos/kubegraf/kubegraf/releases/latest | grep '"tag_name"' | cut -d'"' -f4)
curl -LO "https://github.com/kubegraf/kubegraf/releases/download/${VERSION}/kubegraf-${VERSION#v}-darwin-amd64.tar.gz"
tar xzf "kubegraf-${VERSION#v}-darwin-amd64.tar.gz" && sudo mv kubegraf /usr/local/bin/

Note: You can verify your chip type by clicking the Apple menu () → About This Mac. If it says "Processor: Intel", you have an Intel-based Mac.

Linux

x86_64 / AMD64 Most Common

For standard Intel/AMD 64-bit Linux systems:

VERSION=$(curl -s https://api.github.com/repos/kubegraf/kubegraf/releases/latest | grep '"tag_name"' | cut -d'"' -f4)
curl -LO "https://github.com/kubegraf/kubegraf/releases/download/${VERSION}/kubegraf-${VERSION#v}-linux-amd64.tar.gz"
tar xzf "kubegraf-${VERSION#v}-linux-amd64.tar.gz" && sudo mv kubegraf /usr/local/bin/

Check your architecture: Run uname -m. If it shows x86_64, use this version.

ARM64

For ARM-based 64-bit systems (Raspberry Pi 4/5, AWS Graviton, Oracle Ampere):

VERSION=$(curl -s https://api.github.com/repos/kubegraf/kubegraf/releases/latest | grep '"tag_name"' | cut -d'"' -f4)
curl -LO "https://github.com/kubegraf/kubegraf/releases/download/${VERSION}/kubegraf-${VERSION#v}-linux-arm64.tar.gz"
tar xzf "kubegraf-${VERSION#v}-linux-arm64.tar.gz" && sudo mv kubegraf /usr/local/bin/

Check your architecture: Run uname -m. If it shows aarch64 or arm64, use this version.

Windows

Manual Download Recommended

Direct binary download without package manager - simple and fast.

Which version? Most Windows PCs use x64 (AMD64). Use ARM64 only for Surface Pro X, Windows on ARM devices, or Snapdragon-powered laptops.

⚠️ Windows syntax: The binary is named kubegraf.exe. Always use a backslash (.\) when running from the extracted folder — not ./kubegraf (that is macOS/Linux syntax and will not work on Windows).

After downloading:

  1. Extract the ZIP file to a folder of your choice (e.g., C:\kubegraf). The archive contains kubegraf.exe.
  2. Open PowerShell or Command Prompt, navigate to the folder, and run: 
    cd C:\kubegraf
.\kubegraf.exe --version
.\kubegraf.exe web
Optional: Add to PATH to run kubegraf from anywhere

Open PowerShell and run:

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\kubegraf", [EnvironmentVariableTarget]::User)

Replace C:\kubegraf with your actual folder path. Then close all terminals and open a new PowerShell — you can now run kubegraf web from any directory.

💡 In-App Updates: The app UI supports updating directly from the interface. After clicking the update button, wait approximately 60 seconds for the update to complete.

📖 Need help with PATH? See the detailed PATH troubleshooting section below for step-by-step instructions and common issues.

Scoop Package Manager

For users with Scoop package manager installed

scoop bucket add kubegraf https://github.com/kubegraf/scoop-bucket
scoop install kubegraf

To upgrade: scoop update kubegraf

Verify Installation

After installation, verify KubeGraf is working:

macOS / Linux:

kubegraf --version

Windows (after PATH setup):

kubegraf --version

Windows (running directly from the extracted folder):

.\kubegraf.exe --version

You should see output like:

kubegraf version 1.0.0 (go1.21.0)

Launch the Web Dashboard

Once installed, start the KubeGraf web interface:

macOS / Linux:

kubegraf web

Windows (after PATH setup):

kubegraf web

Windows (running directly from the extracted folder):

.\kubegraf.exe web

Then open http://localhost:3000 in your browser.

💡 Tip: Keep the terminal open while using the dashboard — closing it will stop the server.

  • macOS / Linux — run in the background: kubegraf web &
  • Windows (PowerShell) — run in a new window: Start-Process kubegraf.exe -ArgumentList "web"

Need Help?

📖 Installation Issues?

Having trouble with installation? Check our comprehensive troubleshooting guide for solutions to common issues across all platforms.

View Troubleshooting Guide →

Next Steps

Now that KubeGraf is installed, check out the Quick Start Guide to connect to your first cluster.

Previous
Quick Start
Next
First Cluster