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
kubectlis and who it sends its commands to. - Pick a
kubectlversion compatible with the version of your cluster. - Install
kubectlon Linux in a pinned version, verifying the checksum of the binary withsha256sum --check. - Check the installation with
kubectl version --clientand read the output. - Enable bash autocompletion and the
kalias, then test them. - Recognize the answer of
kubectlwhen 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 version | Compatible kubectl versions |
|---|---|
| 1.37 | 1.36, 1.37, 1.38 |
| 1.36 | 1.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.
curl -fsSL https://dl.k8s.io/release/stable.txtv1.37.2The 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.
-
Set the version and the download address
Terminal window KUBECTL_VERSION=v1.37.2BASE="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
vin front of the number is mandatory. -
Download the binary and its checksum
Terminal window curl -fsSLO "${BASE}/kubectl"curl -fsSLO "${BASE}/kubectl.sha256"The current directory now holds two files,
kubectlandkubectl.sha256. The-foption makescurlfail on an HTTP error: without it, a typo in the version would save an error page under the namekubectl. -
Verify the checksum
Terminal window echo "$(cat kubectl.sha256) kubectl" | sha256sum --checkResult kubectl: OKThe
kubectl.sha256file contains only the checksum, without the file name: theechocommand adds that name, whichsha256sum --checkexpects. You must readkubectl: OK. If you readkubectl: FAILED, followed bysha256sum: WARNING: 1 computed checksum did NOT match, delete both files, start the download again and do not install this binary. -
Install the binary
Terminal window sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectlinstallcopies the file to the right place and sets its owner (root) and its permissions (0755, executable by everyone, writable byrootonly) in a single command. A binary that your account cannot modify is harder to replace unnoticed. -
Delete the downloaded files
Terminal window rm kubectl kubectl.sha256The 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.
brew install kubectlHomebrew picks the binary suited to your processor, Intel or Apple Silicon.
winget install --exact --id Kubernetes.kubectlOpen a new PowerShell terminal after the installation: a terminal that was already open does not know the new path yet.
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.
kubectl version --clientClient Version: v1.37.2Kustomize Version: v5.8.1Look 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.
command -v kubectl/usr/local/bin/kubectlThe 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.
sudo apt install bash-completionOn 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.
source <(kubectl completion bash)echo 'source <(kubectl completion bash)' >> ~/.bashrcMany 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.
echo 'alias k=kubectl' >> ~/.bashrcecho 'complete -o default -F __start_kubectl k' >> ~/.bashrcsource ~/.bashrcTo 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.
complete -p kcomplete -o default -F __start_kubectl kThis 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.
kubectl versionClient Version: v1.37.2Kustomize Version: v5.8.1The 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.
kubectl cluster-infoKubernetes control plane is running at https://127.0.0.1:34201CoreDNS is running at https://127.0.0.1:34201/api/v1/namespaces/kube-system/services/kube-dns:dns/proxyAn 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.
| Symptom | Likely cause | Solution |
|---|---|---|
curl: (22) The requested URL returned error: 404 | Misspelled version, often without the leading v | Check KUBECTL_VERSION=v1.37.2 then restart the download |
kubectl: FAILED and sha256sum: WARNING: 1 computed checksum did NOT match | Incomplete or tampered download, or binary and checksum from different versions or architectures | Delete both files, replay step 1 then the download, and do not install the binary |
Permission denied at the install step | The command was run without sudo | Run it again with sudo |
cannot execute binary file: Exec format error on first launch | Binary built for a different processor than yours | Read uname -m, then download amd64 or arm64 accordingly |
kubectl: command not found | kubectl is not in the PATH, or the installation did not finish | Run command -v kubectl and echo $PATH, then redo step 4 |
kubectl version --client prints a version other than v1.37.2 | An older copy of kubectl comes first in the PATH | Run command -v kubectl and delete the copy that does not come from /usr/local/bin |
| The Tab key suggests files instead of subcommands | bash-completion is missing, or ~/.bashrc was not reloaded | Install bash-completion, open a new terminal, then check with type _init_completion |
Tab works with kubectl but not with k | The complete -o default -F __start_kubectl k line is missing | Add it to ~/.bashrc, then run source ~/.bashrc |
The connection to the server localhost:8080 was refused | No cluster and no kubeconfig: normal situation at this stage | Create a cluster with the next lesson |
Key takeaways
kubectlsends every command to the API of a cluster, reading the address and credentials of the cluster from a kubeconfig file.- The
kubectlversion must stay within one minor version of the cluster API version, newer or older. - Pin the version in the download address (
v1.37.2), instead of downloading the latest stable version every time. - Verify the checksum with
sha256sum --checkbefore installing: onlykubectl: OKallows you to continue. sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectlcopies the binary and sets its owner and permissions in one command.kubectl version --clientcontacts no cluster.command -v kubectltells you which binary really runs.- Completion under bash requires the
bash-completionpackage, and thekalias does not inherit it: addcomplete -o default -F __start_kubectl k. - The
localhost:8080 was refusedmessage signals the absence of a cluster or kubeconfig, not an installation error. With a cluster,kubectl versionadds aServer Versionline andkubectl cluster-infoanswers 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
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
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
Continue the course: Create your first local Kubernetes cluster with kind
A new full quiz with random questions
Work again only on the questions you missed