Use local container images in Minikube

A host Docker image is not necessarily available to Minikube's container runtime. Load it into the intended Minikube profile, or build through Minikube, then use the same image reference in the workload.

Load an image built on the host

Use a specific development tag rather than an implicit latest:

docker build -t my-image:dev-001 .
minikube -p minikube image load my-image:dev-001
minikube -p minikube image ls

Check that the intended image appears. Select the correct profile explicitly when you have several clusters. The architecture must also be compatible with the nodes; loading an image does not translate its executable architecture.

Build through Minikube

minikube -p minikube image build -t my-image:dev-001 .

This uses Minikube's runtime-aware build path. For a multi-node profile, the image-build command supports --all to build on all nodes; its default target is the primary control-plane node. Confirm distribution to every node where your Pod can run rather than assuming a single successful build covers the whole cluster.

The image load workflow loads images across the profile's nodes. Check actual command output and runtime availability if one node still cannot start the workload.

Reuse an in-cluster Docker daemon

For a compatible Minikube configuration using the Docker runtime, a POSIX shell can redirect the Docker client temporarily:

eval "$(minikube -p minikube docker-env)"
docker build -t my-image:dev-001 .
docker image ls

eval "$(minikube -p minikube docker-env -u)"

This changes the current shell's Docker environment. It is not a universal method for every runtime or driver; a cluster using containerd does not become a Docker-runtime cluster merely because the host has Docker installed. Check Minikube's runtime support for your version, and use image load/build when that is clearer. Verify the endpoint before running destructive Docker commands.

Use a valid workload definition

apiVersion: apps/v1
kind: Deployment
metadata:
  name: local-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: local-app
  template:
    metadata:
      labels:
        app: local-app
    spec:
      containers:
        - name: app
          image: my-image:dev-001
          imagePullPolicy: IfNotPresent

IfNotPresent uses an available local image and attempts a pull if it is missing. Never forbids pulling and fails if the image is unavailable. Always normally contacts the registry to resolve the reference, although content matching the resolved digest can be reused locally; it does not necessarily download every layer again.

A registry-qualified name is allowed for a preloaded image. What matters is matching the reference known to the runtime and choosing the intended pull policy. Omitting a tag implies latest; Kubernetes normally defaults that to Always when the object is first created. The policy is not automatically recalculated every time you later edit the image tag.

FAQ

Why ImagePullBackOff? Read Pod events. Check the exact name/tag, pull policy, selected profile and node, runtime image store, registry access, credentials and architecture. A registry prefix alone is not an error.

What after editing code? Build a new tag, load/build it in Minikube, and update the Deployment. A new image in the store does not replace an already running process. Reusing tags can also leave stale images on nodes.

Should I use the registry add-on? It can simplify repeated distribution, but registry reachability and trust differ by driver and host platform. For a larger workflow, use a registry reachable by all nodes with deliberate authentication and transport configuration.

See Using local images with Minikube, Minikube image commands, Kubernetes image pull policies.