Introduction

imagePullPolicy controls when Kubernetes pulls a container image from the registry. It is a small field in the pod template, but it affects rollout behavior, registry traffic, and whether a node reuses a cached image. The important operational point is that you do not usually change it with kubectl set image; you change it by editing or patching the workload spec.

Understand the Available Policies

Kubernetes supports three pull policies:

• 'Always: pull the image every time the container starts.'
• 'IfNotPresent: pull only when the image is not already cached on the node.'
• 'Never: never pull from a registry; the image must already exist on the node.'

If you omit the field, Kubernetes applies defaults based on the image reference. For example, :latest defaults to Always, while a specific tag usually defaults to IfNotPresent. Relying on those defaults is possible, but explicit configuration is easier to review and less surprising during incident work.

Set the Policy in the Manifest

The cleanest way to manage imagePullPolicy is in the YAML that defines the workload.

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: web
5spec:
6  replicas: 2
7  selector:
8    matchLabels:
9      app: web
10  template:
11    metadata:
12      labels:
13        app: web
14    spec:
15      containers:
16        - name: web
17          image: nginx:1.27.4
18          imagePullPolicy: IfNotPresent
19          ports:
20            - containerPort: 80

Apply it with:

kubectl apply -f deployment.yaml

This is the most maintainable path because the desired state remains in version control. If the cluster is recreated or another engineer rolls the deployment later, the pull policy stays consistent.

Patch an Existing Deployment

If the workload already exists and you need to change the pull policy from the terminal, patch the pod template on the controller object.

1kubectl patch deployment web \
2  --type='strategic' \
3  --patch='spec:
4  template:
5    spec:
6      containers:
7      - name: web
8        imagePullPolicy: Always'

That updates the deployment template, which causes Kubernetes to create a new ReplicaSet and roll new pods. You are not mutating a running pod in place; you are changing the template from which future pods are created.

Verify the change with a jsonpath query:

kubectl get deployment web \
  -o jsonpath='{.spec.template.spec.containers[?(@.name=="web")].imagePullPolicy}'
echo

You can also inspect the rollout:

kubectl rollout status deployment/web

Why kubectl set image Is Not Enough

kubectl set image updates the image field, not the pull policy field.

kubectl set image deployment/web web=nginx:1.27.4

That command is useful when you want a different image tag, but it does not answer the question of when the node should re-pull the image. If your operational goal is "always fetch from the registry" or "reuse cached images on the node," you must set imagePullPolicy explicitly in the template.

This distinction matters most when teams publish mutable tags. For example, if someone keeps pushing new bytes to the same tag, IfNotPresent may keep running the cached version, while Always forces a fresh pull on restart. That is one reason immutable version tags are the safer production pattern.

Choose a Sensible Policy

A simple rule works well in most environments:

• Use IfNotPresent with immutable version tags in production.
• Use Always in development only when you truly rely on mutable tags.
• Use Never only in specialized environments where images are preloaded onto every node.

For example, if a CI pipeline publishes myapp:2026-03-07.1, this spec is predictable and efficient:

1containers:
2  - name: api
3    image: registry.example.com/myapp:2026-03-07.1
4    imagePullPolicy: IfNotPresent

The node can reuse the cached image, and the tag itself identifies the exact build.

Common Pitfalls

• Assuming kubectl set image can change imagePullPolicy.
• Using :latest in production and then being surprised by inconsistent rollouts.
• Expecting existing running pods to change behavior without a rollout.
• Setting Never on nodes that do not already contain the image.
• Relying on implicit defaults instead of writing the policy into the manifest.

Summary

• 'imagePullPolicy belongs in the pod template.'
• The most maintainable approach is to declare it in YAML and apply the manifest.
• For an existing deployment, use kubectl patch on the deployment template.
• 'kubectl set image changes the image reference, not the pull policy.'
• In production, pair immutable tags with an explicit IfNotPresent or Always policy based on your rollout model.