Start your free 14-day ContainIQ trial

kubectl command not found | Troubleshooting

In this guide, we help readers effectively troubleshoot the Kubectl command not found error message. Included, we highlight a number of the reasons that the reader might be experiencing this issue.

September 19, 2022
Kumar Harsh
Software Developer

kubectl is the standard command line tool used to interact with Kubernetes clusters. It can connect to all kinds of clusters and provide you with a uniform way of managing your Kubernetes deployments and services. This guide will show you how to solve the common <terminal inline>kubectl command not found<terminal inline> error message.

What Causes the kubectl command not found Issue?

There can be multiple reasons for the <terminal inline>kubectl command not found<terminal inline> issue. Before we dive into how to fix it, let’s see what it looks like:

[user@system ~ % kubectl get pods
zsh: command not found: kubectl

Some of the common reasons you might run into this issue are:

  • kubectl is not installed locally: One of the most frequent reasons <terminal inline>command not found<terminal inline> issues occur is that the tool is not installed; therefore, the terminal is unable to find it.
  • Typo in the command name: If you accidentally made a mistake while typing <terminal inline>kubectl<terminal inline>, the terminal might not be able to identify the right tool and will then return a <terminal inline>command not found<terminal inline> error.
  • Missing execution permissions on kubectl: Your terminal may not have execution permissions on the kubectl tool. In this case, it might not identify <terminal inline>kubectl<terminal inline> as an executable, and it won’t know what to do when you use the <terminal inline>kubectl<terminal inline> command.
  • Missing the kubectl tool in your system’s PATH: Even if you ensure that kubectl is installed locally and you have the right permission on the executable, you might still be unable to use it via the <terminal inline>kubectl<terminal inline> command on the terminal, since the terminal uses PATH variables to locate the tool using aliases like <terminal inline>kubectl<terminal inline>. If an entry for the term <terminal inline>kubectl<terminal inline> isn’t made in your system’s PATH variable, the terminal won’t be able to find the executable unless you specify its full path every time.
  • Docker not running: If you use <terminal inline>wsl<terminal inline> on Windows and you’ve set up the kubectl tool as part of your Docker installation, you might receive this error if Docker isn’t running on your system. This is because the tool is located inside of your Docker runtime, and your WSL command line forwards the <terminal inline>kubectl<terminal inline> command to a path like <terminal inline>/mnt/wsl/docker-desktop/cli-tools/usr/local/bin/kubectl<terminal inline> that is only available when Docker is running.
  • Missing ‘–’ when running kubectl inside minikube: If you’re using minikube’s instance of kubectl and you don’t have a standalone installation of kubectl, you might need to verify that you’re structuring your command properly. A <terminal inline>--<terminal inline> is needed in the command to allow the options to be propagated to the kubectl tool instead of the minikube tool.

How to Fix the kubectl command not found Issue

If you’ve identified one of the above reasons as the cause of your <terminal inline>kubectl command not found<terminal inline> issue, you can use one of these solutions to fix it:

kubectl Is Not Installed Locally

Ensure that you have installed kubectl locally. If you haven’t, follow the installation instructions to set it up on your system. Make sure to add the required permissions and add it to your system’s PATH.

If you’re using kubectl via minikube, make sure you run the kubectl commands in the appropriate format (i.e., <terminal inline>minikube kubectl -- <options<terminal inline>). In this case, you don’t need to install kubectl independently on your system.

Typo in the Command Name

Ensure that you’re typing the tool’s name as <terminal inline>kubectl<terminal inline>. Make sure that all letters are lowercase and that you’re not accidentally using any symbols in the name that may look similar to the name of the command.

Missing Execution Permissions on kubectl

If you’re sure that you have the kubectl binary available on your system and that it’s added to your PATH, verify that your terminal has the necessary permission to execute it. If not, use a tool like chmod to add the required permission. Here’s how you can do this:

chmod +x /usr/local/bin/kubectl # replace this with the path to your kubectl binary

You can also go <terminal inline>sudo<terminal inline> to solve this problem. However, using <terminal inline>sudo<terminal inline> on a regular basis is not recommended. Instead, figure out the right permissions needed and add them to the binary file for smooth usage.

Missing the kubectl Tool in Your System’s PATH

If you’ve identified that you have a local installation of the kubectl tool and you’re able to access it by providing its full path (for instance, <terminal inline>/path/to/kubectl.exe<terminal inline> instead of just <terminal inline>kubectl<terminal inline>), you need to add it to your system’s PATH variable to reference it as just <terminal inline>kubectl<terminal inline> from your command line. Depending on your operating system, you’ll need to find the correct way to add it to your PATH. For *nix, here’s how you can move the binary into the PATH location:

sudo mv ./kubectl /usr/local/bin/kubectl

Alternatively, you could create an alias for the command — you could set the value of <terminal inline>kubectl<terminal inline> to point to <terminal inline>/path/to/kubectl.exe<terminal inline>. This comes in handy when you don’t have permission to make changes to your system’s PATH variable (for example, on a corporate system).

Docker Not Running

If your kubectl CLI is based inside your Docker installation, start up Docker and see whether the command starts working again.

Missing ‘–’ When Running kubectl Inside minikube

If you’re using kubectl inside minikube, you need to add <terminal inline>--<terminal inline> in your command to ensure that it’s correctly formatted.

minikube kubectl -- get pods

The double dash (<terminal inline>--<terminal inline>) is used to signify the end of command options. Using a <terminal inline>--<terminal inline> after <terminal inline>minikube kubectl<terminal inline> means that the options that you provide are meant to be passed on to kubectl and not minikube.

Final Thoughts

The <terminal inline>kubectl command not found<terminal inline> error can be tricky to solve, as it can occur for many reasons. In this guide, we presented a roundup of these reasons and solutions that can help you fix the issue quickly.

Start your free 14-day ContainIQ trial
Start Free TrialBook a Demo
No card required
Kumar Harsh
Software Developer

Kumar is a software developer and technical author. He has written for a number of software companies including LogRocket and Career Karma. Kumar previously worked for Goldman Sachs as a Summer Analyst. He is currently pursuing a Bachelor of Technology in Computer Science at the National Institute of Technology, Patna.