Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Install kubectl on Linux and check its version

By updated

Improve this page

Logo Kubernetes

kubectl is the command-line program that sends your orders to a Kubernetes cluster. This lesson installs it on Linux in a pinned version, v1.37.2, after verifying the SHA-256 checksum of the binary, then enables autocompletion and the k alias. You also learn to pick a version compatible with your cluster and to recognize the localhost:8080 message that kubectl prints as long as no cluster exists. It is aimed at a beginner who can use a Linux terminal, and it prepares the creation of your first cluster in the next lesson.

What you will learn

  • Say what kubectl is and who it sends its commands to.
  • Pick a kubectl version compatible with the version of your cluster.
  • Install kubectl on Linux in a pinned version, verifying the checksum of the binary with sha256sum --check.
  • Check the installation with kubectl version --client and read the output.
  • Enable bash autocompletion and the k alias, then test them.
  • Recognize the answer of kubectl when no cluster is configured, and check the connection when there is one.

Prerequisites

You can open a Linux terminal, run a command and read its output, and you have sudo rights on the machine, where curl is installed (sudo apt install curl if it is missing). You have read the lesson key concepts: the words cluster, Node and Pod should be familiar. No cluster is needed, the next lesson creates one.

What is kubectl, and what does it talk to?

kubectl (read "cube-ctl" or "cube-control") is the official Kubernetes client. It does not run any container itself: every command you type becomes an HTTPS request sent to the API of the cluster, the entry point through which Kubernetes receives all orders. The cluster carries out the action, kubectl prints the answer.

To know which cluster to talk to, kubectl reads a configuration file called kubeconfig, found by default in ~/.kube/config. It holds the address of the API and the credentials to connect to it. This lesson does not open that file: it is detailed in the lesson Kubeconfig and contexts. Just remember that a client without a cluster can do nothing: it needs a cluster to talk to.

Which version of kubectl should you install?

Install a version of kubectl that differs by at most one minor version from that of your cluster's API, newer or older. In v1.37.2, 1 is the major version, 37 the minor version and 2 the patch number. Only the minor version matters for compatibility: a kubectl 1.37.2 works with a 1.37.0 cluster. The rule comes from the version skew policy of the Kubernetes project.

Cluster API versionCompatible kubectl versions
1.371.36, 1.37, 1.38
1.361.35, 1.36, 1.37

This course uses 1.37.0 clusters, so you install kubectl v1.37.2, the stable version as of November 11, 2026. You can look up the current stable version with the following command, which queries the official download server.

Look up the stable kubectl version
curl -fsSL https://dl.k8s.io/release/stable.txt
Result on November 11, 2026
v1.37.2

The result changes with every new release, which is why the commands in this lesson write the version out instead of looking it up on every run. A pinned installation gives you the same binary tomorrow as today, and you choose when to move to a newer version. Compatibility between the components of the cluster itself comes up when you upgrade a cluster: it is covered in upgrading a Kubernetes cluster.

How do you install kubectl on Linux?

To install kubectl on Linux, download the binary of the chosen version, verify its SHA-256 checksum against the .sha256 file published next to it, then copy it into /usr/local/bin with install. A checksum is a value computed from the content of the file: if a single byte changes during the download, the checksum changes too. Comparing your binary with the official checksum therefore proves that you are running exactly what the project published. The commands below are for an amd64 processor (uname -m prints x86_64); on an arm64 processor (aarch64), replace amd64 with arm64.

  1. Set the version and the download address

    Terminal window
    KUBECTL_VERSION=v1.37.2
    BASE="https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64"

    These two lines download nothing: they write the version once, so that the binary and its checksum necessarily come from the same version. The v in front of the number is mandatory.

  2. Download the binary and its checksum

    Terminal window
    curl -fsSLO "${BASE}/kubectl"
    curl -fsSLO "${BASE}/kubectl.sha256"

    The current directory now holds two files, kubectl and kubectl.sha256. The -f option makes curl fail on an HTTP error: without it, a typo in the version would save an error page under the name kubectl.

  3. Verify the checksum

    Terminal window
    echo "$(cat kubectl.sha256) kubectl" | sha256sum --check
    Result
    kubectl: OK

    The kubectl.sha256 file contains only the checksum, without the file name: the echo command adds that name, which sha256sum --check expects. You must read kubectl: OK. If you read kubectl: FAILED, followed by sha256sum: WARNING: 1 computed checksum did NOT match, delete both files, start the download again and do not install this binary.

  4. Install the binary

    Terminal window
    sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

    install copies the file to the right place and sets its owner (root) and its permissions (0755, executable by everyone, writable by root only) in a single command. A binary that your account cannot modify is harder to replace unnoticed.

  5. Delete the downloaded files

    Terminal window
    rm kubectl kubectl.sha256

    The installed copy is enough. Keeping the downloaded binary in your working directory serves no purpose and adds confusion about which one is running.

What about macOS and Windows?

On macOS and Windows, a package manager is enough. It installs the stable version of the moment, which can therefore be newer than 1.37.2: read the version with the command in the next section, and check that it stays within one minor version of your cluster.

Terminal window
brew install kubectl

Homebrew picks the binary suited to your processor, Intel or Apple Silicon.

How do you check the installation?

The kubectl version --client command prints the version of the installed program, without contacting any cluster: it therefore works before you have one. The --client option asks for exactly that, the client version alone.

Terminal window
kubectl version --client
Result
Client Version: v1.37.2
Kustomize Version: v5.8.1

Look at the first line: it must show v1.37.2, the version you installed. The second line gives the version of Kustomize bundled in kubectl, a tool for customizing Kubernetes files that you do not have to install or use here. Its number may differ from the one shown above.

If the command answers command not found, or if it prints a version other than the expected one, ask the shell which file it runs.

Terminal window
command -v kubectl
Result
/usr/local/bin/kubectl

The path printed must be the one where you installed the binary. Any other path means that an older copy of kubectl sits earlier in your PATH (the list of directories where the shell looks for programs) and comes before the new one. Delete that older copy, or move /usr/local/bin to the front of the PATH.

How do you enable autocompletion?

Autocompletion finishes a command when you press the Tab key: kubectl ver becomes kubectl version. It saves many typos and lists the available subcommands. Under bash, it needs the bash-completion package: the script generated by kubectl completion bash does not work without it, on every distribution. Install it first if it is missing.

Install bash-completion (Debian, Ubuntu)
sudo apt install bash-completion

On Rocky Linux or AlmaLinux, the equivalent command is sudo dnf install bash-completion. After the installation, open a new terminal and run type _init_completion: if the command still fails, add source /usr/share/bash-completion/bash_completion to ~/.bashrc. Then kubectl completion bash generates the completion script. You load it into the current shell with source, then add the same line to ~/.bashrc so that it applies in every new terminal.

Enable kubectl completion
source <(kubectl completion bash)
echo 'source <(kubectl completion bash)' >> ~/.bashrc

Many kubectl users create the k alias, shorter to type. The alias alone does not get completion: you have to tell bash to reuse the one of kubectl for k.

Create the k alias with its completion
echo 'alias k=kubectl' >> ~/.bashrc
echo 'complete -o default -F __start_kubectl k' >> ~/.bashrc
source ~/.bashrc

To check, type kubectl ver then press Tab: the shell must complete it to kubectl version. Do the same with k ver. You can also query bash directly with complete -p k.

Terminal window
complete -p k
Result
complete -o default -F __start_kubectl k

This line shows that the k alias is wired to the completion of kubectl. Completion of subcommands and options works without a cluster; Pod or Node names only appear once a cluster is available. Under zsh, the equivalent line is source <(kubectl completion zsh), placed in ~/.zshrc after autoload -Uz compinit && compinit.

What does kubectl answer when no cluster is configured?

With no cluster configured, kubectl version prints the client version, then a connection error to localhost:8080. This message is not an installation failure: it proves that kubectl works and is looking for a cluster that does not exist yet. Run the command without the --client option, which also asks for the server version.

Terminal window
kubectl version
Result
Client Version: v1.37.2
Kustomize Version: v5.8.1
The connection to the server localhost:8080 was refused - did you specify the right host or port?

The first two lines are identical to the previous section. The last line describes the situation: kubectl found no kubeconfig file, tried the default address localhost:8080, and nobody is listening there. The kubectl get nodes command ends with the same line, preceded by error lines detailing the refused connection attempts. As long as you see this message, the next step is to create a cluster. The next lesson creates a cluster with kind: the tool writes the kubeconfig itself, and this message disappears.

How do you check that kubectl reaches a cluster?

When a cluster and its kubeconfig exist (as in the lab), the same commands succeed. Run kubectl version again: after the client lines, a Server Version line gives the version of the cluster API. Compare it with that of kubectl using the skew rule from the section on versions. Complete the check with kubectl cluster-info, which queries the cluster API.

Terminal window
kubectl cluster-info
Result with a kind cluster
Kubernetes control plane is running at https://127.0.0.1:34201
CoreDNS is running at https://127.0.0.1:34201/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

An answer with an address proves that the whole chain works: the binary, the kubeconfig and the cluster API. The port number is picked at random when the cluster is created, yours will be different.

Put it into practice

A kind cluster running Kubernetes v1.37.0 is waiting on the lab machine and your kubeconfig is in place: only the tool is missing. The lab starts from a machine without kubectl, without completion, without the k alias and without the bash-completion package. You install the official binary, enable completion and the alias, then check that kubectl reaches the cluster. The launch command is dsoxlab run k8s-installer-kubectl.

The validation reads the state of the machine, not the commands you typed. It first checks the installation: kubectl is in /usr/local/bin, executable, owned by root, neither the group nor others can modify it, and it is the one the PATH finds first. It then checks the client version in v1.37, the official checksum of that version, bash completion in a new interactive shell (a real completion of kubectl ver) and the completion of the k alias, identical to that of kubectl.

Finally, it checks that the kubectl you installed really reads the prepared cluster. To do so, it compares what it sees with the state of the cluster itself, without trusting the output of kubectl version.

Troubleshooting

Almost all the errors in this lesson come from an incomplete download, a missing permission or a wrong PATH. The table gives the symptom you see, what most often causes it and the fix.

SymptomLikely causeSolution
curl: (22) The requested URL returned error: 404Misspelled version, often without the leading vCheck KUBECTL_VERSION=v1.37.2 then restart the download
kubectl: FAILED and sha256sum: WARNING: 1 computed checksum did NOT matchIncomplete or tampered download, or binary and checksum from different versions or architecturesDelete both files, replay step 1 then the download, and do not install the binary
Permission denied at the install stepThe command was run without sudoRun it again with sudo
cannot execute binary file: Exec format error on first launchBinary built for a different processor than yoursRead uname -m, then download amd64 or arm64 accordingly
kubectl: command not foundkubectl is not in the PATH, or the installation did not finishRun command -v kubectl and echo $PATH, then redo step 4
kubectl version --client prints a version other than v1.37.2An older copy of kubectl comes first in the PATHRun command -v kubectl and delete the copy that does not come from /usr/local/bin
The Tab key suggests files instead of subcommandsbash-completion is missing, or ~/.bashrc was not reloadedInstall bash-completion, open a new terminal, then check with type _init_completion
Tab works with kubectl but not with kThe complete -o default -F __start_kubectl k line is missingAdd it to ~/.bashrc, then run source ~/.bashrc
The connection to the server localhost:8080 was refusedNo cluster and no kubeconfig: normal situation at this stageCreate a cluster with the next lesson

Key takeaways

  1. kubectl sends every command to the API of a cluster, reading the address and credentials of the cluster from a kubeconfig file.
  2. The kubectl version must stay within one minor version of the cluster API version, newer or older.
  3. Pin the version in the download address (v1.37.2), instead of downloading the latest stable version every time.
  4. Verify the checksum with sha256sum --check before installing: only kubectl: OK allows you to continue.
  5. sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl copies the binary and sets its owner and permissions in one command.
  6. kubectl version --client contacts no cluster. command -v kubectl tells you which binary really runs.
  7. Completion under bash requires the bash-completion package, and the k alias does not inherit it: add complete -o default -F __start_kubectl k.
  8. The localhost:8080 was refused message signals the absence of a cluster or kubeconfig, not an installation error. With a cluster, kubectl version adds a Server Version line and kubectl cluster-info answers with the API address.

Test your knowledge

Eight questions on the gestures of the lesson: choosing the right version, reading the result of a checksum verification, wiring completion to the alias and interpreting the message kubectl prints without a cluster.

Knowledge check

Check what you have learned with this interactive quiz

8 questions
5 min
80% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer