Introduction

Upgrading kubectl is straightforward, but doing it safely means more than downloading the newest binary you can find. A good process checks the currently installed version, chooses a target version that matches cluster support expectations, installs from an official source, and then verifies that your shell is actually using the new binary.

Check the Current Client First

Before changing anything, inspect the current client version and, if possible, compare it with the cluster version.

kubectl version --client --output=yaml
kubectl version --output=yaml

This gives you a baseline and helps explain later problems. In many environments, keeping the client within one minor version of the control plane is a practical rule.

Install a Pinned Version from the Official Release

For reproducibility, install a specific release instead of depending on whatever a package manager serves today.

1KVER="v1.31.3"
2OS="darwin"
3ARCH="arm64"
4
5curl -LO "https://dl.k8s.io/release/${KVER}/bin/${OS}/${ARCH}/kubectl"
6curl -LO "https://dl.k8s.io/release/${KVER}/bin/${OS}/${ARCH}/kubectl.sha256"
7
8echo "$(cat kubectl.sha256)  kubectl" | shasum -a 256 --check
9chmod +x kubectl
10sudo mv kubectl /usr/local/bin/kubectl

Change OS and ARCH for your platform, such as linux and amd64. Pinning the version keeps local workstations and CI machines aligned.

Verify Path Resolution After Install

An upgrade can appear to succeed while the shell still resolves an older binary from somewhere else in PATH. Always verify which executable is being used.

which kubectl
kubectl version --client
kubectl config current-context

If the version is unchanged, search for duplicate binaries and remove or reorder them.

Use Package Managers Carefully

Package managers are convenient for personal machines, but they can hide version drift. Use them when convenience matters more than deterministic pinning.

brew update
brew upgrade kubernetes-cli
kubectl version --client

For teams, an internal setup script or version manager is usually better than letting each machine float independently.

Manage Multiple Versions When Needed

If you support several clusters with different lifecycle windows, a version manager can be cleaner than repeatedly replacing one global binary.

1asdf plugin add kubectl
2asdf install kubectl 1.31.3
3asdf local kubectl 1.31.3
4kubectl version --client

This is especially useful in repositories where the supported kubectl version should travel with the project.

Keep a Rollback Path

CLI upgrades sometimes break scripts, shell completions, or plugin expectations. Back up the current binary before replacing it so rollback is immediate.

1cp /usr/local/bin/kubectl /usr/local/bin/kubectl.prev
2sudo mv kubectl /usr/local/bin/kubectl
3
4# rollback if needed
5sudo mv /usr/local/bin/kubectl.prev /usr/local/bin/kubectl
6kubectl version --client

A rollback step is simple, but it matters when deployment tooling depends on stable client behavior.

In shared environments, write the chosen kubectl version into onboarding docs or repository setup instructions. That keeps local laptops, ephemeral CI runners, and operational runbooks aligned. Version drift is much easier to prevent than to debug after a failed deployment or a confusing change in command output.

Common Pitfalls

One pitfall is upgrading locally while CI still uses an older client version. That creates subtle differences in command behavior and deployment output.

Another is trusting a package manager to pick the right version for your environment. Convenience is not the same as compatibility.

Teams also forget checksum verification when downloading binaries directly. Skipping that step removes a useful integrity check for a very small time savings.

Summary

• Check the current client and cluster versions before upgrading.
• Prefer pinned official releases when reproducibility matters.
• Verify checksum, binary path, and client version after installation.
• Use package managers carefully if your team needs deterministic tooling.
• Keep a rollback path so you can recover quickly from an incompatible upgrade.