Fixing the 'kubectl command not found' error on Linux

What the 'kubectl: command not found' Error Means

The 'kubectl: command not found' (or 'bash: kubectl: command not found') error appears in a Linux terminal when the system cannot find the kubectl executable file in the directories listed in the PATH environment variable. This means that either kubectl is not installed on your system, it is installed but its path is not added to PATH, or the path is specified incorrectly.

The error is typically accompanied by exit code 127 (in bash), which indicates that the command was not found.

Possible Causes

1. kubectl is not installed. You are trying to use kubectl without having installed the Kubernetes client first.
2. kubectl is installed but not in PATH. You may have installed kubectl in a custom directory (e.g., ~/bin or /opt/kubectl), but that directory is not included in the PATH variable.
3. Incorrect path in PATH. The PATH contains an incorrect path to the kubectl executable, for example due to a typo or a change in the file's location.
4. Shell issues. A shell is being used that does not load configuration files (e.g., ~/.bashrc) where kubectl was added to PATH.
5. Corrupted installation. kubectl is installed, but the executable file is missing or damaged.

Solutions

Method 1: Install kubectl

If kubectl is not installed, you need to install it. There are several installation methods depending on your Linux distribution.

For Ubuntu/Debian:

# Update package index
sudo apt-get update

# Install kubectl
sudo apt-get install kubectl

For CentOS/RHEL:

# Install kubectl via yum
sudo yum install kubectl

For Fedora:

# Install kubectl via dnf
sudo dnf install kubectl

Alternative installation via the official Kubernetes repository:

You can install kubectl directly from the Kubernetes website, which ensures you get the latest version:

# Download the latest stable version (example for amd64)
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# Add execute permissions
chmod +x kubectl

# Move to a directory in PATH (e.g., /usr/local/bin)
sudo mv kubectl /usr/local/bin/

# Verify installation
kubectl version --client

Method 2: Configure the PATH Variable

If kubectl is already installed but the command is not found, the path to the executable might not be added to PATH.

1. Find the location of kubectl:

   # Search in standard directories
   sudo find / -name kubectl 2>/dev/null
   # Or if you know the approximate path
   ls /usr/local/bin/kubectl
   

2. Check your current PATH:

   echo $PATH
   

   
   Ensure the directory containing kubectl (e.g., /usr/local/bin) appears in the output.
3. If the directory is not in PATH, add it: Open the ~/.bashrc file (for bash) or ~/.zshrc (for zsh) in a text editor and add the line:

   export PATH=$PATH:/path/to/directory
   

   
   For example, if kubectl is located in /usr/local/bin (which is typical) and that directory is not in PATH, add:

   export PATH=$PATH:/usr/local/bin
   

4. Apply the changes:

   source ~/.bashrc   # for bash
   # or
   source ~/.zshrc    # for zsh
   

   
   Or simply restart the terminal.
5. Verify that kubectl is now available:

   which kubectl
   kubectl version --client
   

Method 3: Create a Symbolic Link

If kubectl is installed in a non-standard directory and you do not want to modify PATH, you can create a symbolic link in a directory that is already in PATH (e.g., /usr/local/bin):

# Assuming kubectl is located at /opt/kubectl/bin/kubectl
sudo ln -s /opt/kubectl/bin/kubectl /usr/local/bin/kubectl

# Verification
kubectl version --client

Prevention

• Install kubectl via official repositories or package managers to automatically add it to PATH.
• Check PATH after installation using the echo $PATH command to ensure the directory containing kubectl is included.
• Use standard paths for installing binaries, such as /usr/local/bin or /usr/bin, which are typically already in PATH.
• If installing manually, always add the path to PATH in your shell configuration file (e.g., ~/.bashrc).