Installing Minikube on Debian

Minikube is a practical way to run a small Kubernetes cluster on a Debian workstation or development instance. This guide installs Minikube with the Docker driver, starts a named profile, runs a temporary deployment, and removes the test resources afterward.

This is a local development setup, not a production Kubernetes distribution. The commands target Debian 12 (Bookworm), Debian 13 (Trixie), or a compatible newer Debian release on an x86-64 host.

The goal is a repeatable local baseline rather than a particular Minikube release number. Minikube and Kubernetes change over time, so the release documentation remains the authority for supported versions and driver behavior. The commands deliberately verify each boundary: the Debian host, Docker, the Minikube profile, the Kubernetes node, and a real workload. That makes a later failure easier to classify. For example, a failed docker run is a runtime problem, while a successful Docker test followed by a failed rollout belongs in the cluster or workload layer.

Run the commands as the same non-root user who will use Minikube afterward. Mixing sudo minikube with normal-user commands creates separate configuration and cache locations, which can make a healthy cluster appear to be missing. Keeping one user and one named profile throughout the walkthrough avoids that confusing split.

Key Takeaways

• You will have a Docker-backed Minikube profile named local-kube-cluster.
• Reserve at least 2 CPUs, 4 GiB of memory, and 20 GiB of free disk space for a comfortable first run.
• The Docker driver avoids a second virtual machine, but it still needs a working Docker daemon and permission to access it.

What Is Minikube?

Minikube runs a single-node Kubernetes cluster locally so you can develop manifests, test controllers, and follow tutorials without provisioning a remote cluster. The Docker driver runs the node inside a container managed by Docker.

The driver is the important choice: Minikube manages the Kubernetes node, while Docker provides the container runtime and host-level isolation. If either layer is unhealthy, Kubernetes startup errors can be misleading.

The Mental Model

Think of the installation as four independent checks:

1. Host capacity: the machine has enough CPU, memory, disk, and network access.
2. Container runtime: Docker is installed, running, and usable by the current user.
3. Cluster profile: Minikube creates and stores a named cluster configuration. A profile can retain a driver choice and resource settings from an earlier attempt.
4. Kubernetes workload: a Ready node only proves the control plane started. A deployment and service smoke test proves that the cluster can schedule a workload and expose it through the selected driver.

This model also explains the safest troubleshooting order: check the host first, then Docker, then the Minikube profile, and only then the Kubernetes workload.

Prerequisites

• Debian 12, Debian 13, or a compatible newer Debian release
• x86-64 Linux, unless you download the matching Minikube architecture binary
• A non-root user with sudo access
• At least 2 CPUs, 4 GiB RAM, and 20 GiB of free disk space
• Outbound access to Debian, Docker, Kubernetes, and Minikube download endpoints
• systemd available if you want Docker managed as a system service

Walkthrough

1. Confirm the Debian host has enough capacity

Update the package index, install the utilities used by the setup, and inspect the resources before downloading anything.

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y ca-certificates curl gnupg lsb-release

nproc
free -h
sudo df -h /

Do not continue with the default profile if the host has fewer than 2 CPUs or less than 4 GiB of usable memory. A cluster can technically start with less, but image pulls and system pods will compete for the same constrained resources.

2. Install and verify Docker Engine

Before continuing, install Docker Engine by following the dedicated Install Docker Engine on Debian guide. It uses Docker's official APT repository and covers conflicting packages, repository key configuration, daemon access, firewall considerations, and cleanup.

After Docker is installed, verify it as the same user who will run Minikube:

sudo systemctl enable --now docker
sudo systemctl is-active docker
docker version
docker run --rm hello-world

If docker version reports a permission error, follow the non-root access and new-login-session instructions in the Docker guide. The Docker group grants root-equivalent control over the host, so only trusted users should receive this access.

3. Install the Minikube binary

Download the latest stable x86-64 Linux binary from Minikube's official release location and install it in /usr/local/bin:

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install -o root -g root -m 0755 minikube-linux-amd64 /usr/local/bin/minikube
rm minikube-linux-amd64

Verify the installation and make Docker the default driver:

minikube version
minikube config set driver docker

For ARM64, download the matching binary from the Minikube releases page instead of the x86-64 file above.

4. Install kubectl locally

Install the latest stable x86-64 kubectl binary, verify its SHA-256 checksum, and move it into /usr/local/bin:

set -e
KUBECTL_VERSION="$(curl -fsSL https://dl.k8s.io/release/stable.txt)"
curl -LO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl"
curl -fLO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl.sha256"
echo "$(cat kubectl.sha256)  kubectl" | sha256sum --check
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
rm kubectl kubectl.sha256

Verify the local client:

kubectl version --client

The commands above target x86-64 Linux. For an ARM64 host, replace amd64 in both download URLs with arm64.

Keep the client and cluster lifecycle separate. kubectl is the command-line client installed on the Debian host, while Minikube owns the local cluster and its certificates. Starting the profile writes or updates a context in the current user's kubeconfig. After activating local-kube-cluster, kubectl uses that active context by default. Run kubectl config get-contexts if you need to inspect available contexts.

5. Start a Docker-backed cluster profile

Create a named profile with explicit resources. Naming the profile makes it possible to inspect, stop, and delete this cluster without affecting another Minikube profile.

minikube start \
  --profile=local-kube-cluster \
  --driver=docker \
  --memory=4096 \
  --cpus=2

Make the named profile active, then check both the Minikube state and the Kubernetes node:

minikube profile local-kube-cluster
minikube status --profile=local-kube-cluster
minikube profile
kubectl config current-context
kubectl get nodes
kubectl get pods --all-namespaces

The minikube profile command should now print local-kube-cluster, and kubectl config current-context should show the same context. The profile should report Running, one node should report Ready, and system pods may need a short time to settle during the first image pull.

6. Run and remove a Kubernetes smoke test

Create a temporary deployment, expose it as a NodePort service, and wait for the rollout:

kubectl create deployment minikube-smoke \
  --image=kicbase/echo-server:1.0
kubectl expose deployment minikube-smoke \
  --type=NodePort --port=8080
kubectl rollout status deployment/minikube-smoke \
  --timeout=120s
kubectl get deployment,service,pods

Ask Minikube for a URL to the service:

minikube service minikube-smoke --profile=local-kube-cluster --url

Remove the temporary objects after the test:

kubectl delete service minikube-smoke
kubectl delete deployment minikube-smoke

Debugging & Common Pitfalls

Docker permission denied

If Docker works with sudo but not as your normal user, the current shell has not picked up the new group membership. Run groups and id -nG, start a new login session, and retry docker run --rm hello-world.

Insufficient resources

Check free -h, nproc, and df -h /. Stop competing workloads or increase the instance size before changing Kubernetes settings. Reducing memory can make the cluster appear to start while leaving system pods unable to schedule reliably.

Profile uses the wrong driver

Profiles retain configuration. Inspect existing profiles and recreate the named profile if it was previously started with another driver:

minikube profile list
minikube delete --profile=local-kube-cluster
minikube start --profile=local-kube-cluster --driver=docker --memory=4096 --cpus=2

Startup fails behind a proxy

Image pulls and package downloads need network access from both the host and Docker. Configure the proxy according to your environment, then inspect the profile diagnostics:

minikube logs --profile=local-kube-cluster
minikube status --profile=local-kube-cluster

A failed start leaves stale resources

Delete the profile and retry only after checking the logs. Repeating minikube start without removing a partially created profile can preserve the original driver or resource settings.

FAQ

Is Minikube suitable for production?

No. Minikube is designed for local development, learning, and repeatable experiments. Use a production-oriented Kubernetes distribution or managed service when you need high availability, durable operations, and multi-node failure handling.

Why install standalone kubectl?

The standalone client provides the normal Kubernetes workflow and can switch among contexts with kubectl config get-contexts. Installing it once also keeps the commands in this guide consistent with other Kubernetes tools and scripts. Minikube still manages the cluster and writes the local-kube-cluster context into your kubeconfig.

Why use the Docker driver on Debian?

It is usually the simplest option when Docker is already part of the development workflow. It avoids managing a second virtual machine, though it still consumes host CPU, memory, disk, and Docker daemon resources.

What should I do when the profile is no longer needed?

Stop it to retain its downloaded data and configuration:

minikube stop --profile=local-kube-cluster

Delete it to remove the profile and its resources:

minikube delete --profile=local-kube-cluster