Command Palette

Search for a command to run...

GitHubGitHub

Minikube Installation Guide

Install Minikube v1.39 on Linux, macOS and Windows, start a local Kubernetes cluster with the right driver, manage add-ons, load images and troubleshoot common failures.

Minikube runs a single-node Kubernetes cluster locally, inside a container or a virtual machine. This guide installs Minikube v1.39 and walks through the commands you use every day.

Prerequisites

  • 2 CPUs or more
  • 2 GB of free memory (4 GB or more recommended)
  • 20 GB of free disk space
  • Internet access to pull images
  • A container or virtual machine driver: Docker, Podman, QEMU, KVM, Hyper-V, VirtualBox, VMware Fusion/Workstation or Parallels

Installation Instructions

Linux

# Download the latest stable release (x86_64)
curl -LO https://github.com/kubernetes/minikube/releases/latest/download/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube && rm minikube-linux-amd64
 
# On ARM64 use minikube-linux-arm64 instead

macOS

# Homebrew (recommended)
brew install minikube
 
# Or the binary
curl -LO https://github.com/kubernetes/minikube/releases/latest/download/minikube-darwin-arm64
sudo install minikube-darwin-arm64 /usr/local/bin/minikube

If which minikube fails after a Homebrew install, relink it:

brew unlink minikube
brew link minikube

Windows

# Windows Package Manager
winget install Kubernetes.minikube
 
# Chocolatey
choco install minikube
 
# Or the .exe installer
# https://storage.googleapis.com/minikube/releases/latest/minikube-installer.exe

Install kubectl

Minikube can download a matching kubectl for you, but having a standalone client is handy:

KUBECTL_VERSION="$(curl -sL https://dl.k8s.io/release/stable.txt)"
curl -LO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

Starting the Cluster

# Start with the default driver (Docker if it is available)
minikube start
 
# Explicitly choose a driver
minikube start --driver=docker
minikube start --driver=podman
minikube start --driver=kvm2
 
# Give the cluster more resources
minikube start --cpus=4 --memory=8192mb
 
# Start a multi-node cluster
minikube start --nodes=3
 
# Pin a Kubernetes version (one of the three latest minor releases)
minikube start --kubernetes-version=v1.36.0
 
# Use containerd instead of the Docker runtime inside the node
minikube start --container-runtime=containerd

On Windows, Hyper-V must be enabled before starting Minikube:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

Verify the Cluster

# Cluster status
minikube status
 
# Nodes
kubectl get nodes -o wide
 
# System pods
kubectl get pods -A
 
# Or use the bundled kubectl
minikube kubectl -- get pods -A

Add an alias so kubectl always targets the cluster:

echo 'alias kubectl="minikube kubectl --"' >> $HOME/.bashrc
source $HOME/.bashrc

Deploying Your First Application

# Create a deployment and expose it
kubectl create deployment hello-minikube --image=kicbase/echo-server:1.0
kubectl expose deployment hello-minikube --type=NodePort --port=8080
 
# Open it in a browser
minikube service hello-minikube
 
# Or forward the port instead
kubectl port-forward service/hello-minikube 7080:8080

For a LoadBalancer service, run the tunnel in a separate terminal:

minikube tunnel

Then read the external IP from kubectl get services.

Managing Add-ons

# List the available add-ons
minikube addons list
 
# Enable the ingress controller
minikube addons enable ingress
 
# Enable the dashboard
minikube addons enable dashboard
 
# Open the dashboard
minikube dashboard
 
# Disable an add-on
minikube addons disable ingress

Working with Images

Building locally is slow because the image has to travel to the node. Load it directly instead:

# Build with the host daemon
docker build -t my-app:1.0 .
 
# Load the image into the Minikube node
minikube image load my-app:1.0
 
# Or point your shell at the in-cluster daemon
eval $(minikube docker-env)
docker build -t my-app:1.0 .
 
# Return to the host daemon
eval $(minikube docker-env -u)

Managing Clusters

# Create a second cluster with an older Kubernetes version
minikube start -p aged --kubernetes-version=v1.35.0
 
# List the profiles
minikube profile list
 
# Switch between them
minikube profile aged
 
# Pause and resume
minikube pause
minikube unpause
 
# Stop and delete
minikube stop
minikube delete
minikube delete --all
 
# Change the defaults for the next start
minikube config set memory 9001
minikube config set cpus 4

Troubleshooting

Best Practices

  1. Use a named profile per project so teams do not overwrite each other's cluster:

    minikube start -p payments

  2. Pin the Kubernetes version in CI so a new Minikube release cannot change your test matrix under you.

  3. Load images instead of pulling them — it is dramatically faster:

    minikube image build -t my-app:1.0 .

  4. Keep the cluster small — one node with 2 CPUs is enough for most development work.

  5. Reset when things get weird — a fresh cluster is faster to fix than a broken one:

    minikube delete
minikube start

Next Steps

Istio

Install Istio 1.31 with istioctl, choose the right configuration profile, enable sidecar or ambient mode, install the observability add-ons and verify the mesh.

OpenShift

Install OpenShift Container Platform 4.22 or OpenShift Local (CRC) for local development, install the oc CLI and deploy a production cluster with the agent-based installer.