Skip to main content
Find answers to commonly asked questions about kubectx and kubens.

​
General Questions

kubectx is a tool to switch between Kubernetes contexts (clusters) on kubectl faster.kubens is a tool to switch between Kubernetes namespaces (and configure them for kubectl) easily.Both tools are designed to make working with multiple Kubernetes clusters and namespaces more efficient by providing simple, fast commands with interactive capabilities.
Starting with v0.9.0, kubectx and kubens were rewritten in Go. Both implementations are maintained:Bash implementation:
  • Original implementation
  • Small bash scripts
  • Stable and proven
  • Still maintained for compatibility
Go implementation:
  • Newer, cross-platform compatible
  • Better performance
  • Receives new features
  • Available as binaries from the Releases page
  • Recommended for new installations
Both implementations work the same way and have the same functionality.
Yes! You can install them as kubectl plugins using Krew:
kubectl krew install ctx
kubectl krew install ns
After installing, use them as:
  • kubectl ctx instead of kubectx
  • kubectl ns instead of kubens
Note: Installing via Krew does not include shell completion scripts. For completions, choose another installation method or install the scripts manually.
No, they are independent tools. You can install and use either or both based on your needs:
  • Use kubectx if you work with multiple clusters
  • Use kubens if you work with multiple namespaces within a cluster
  • Use both if you work with multiple clusters and namespaces (most common)
Most installation methods install both tools together.

​
Installation Questions

There are multiple installation methods available depending on your operating system:macOS/Linux:Linux:Windows:See the full Installation guide for detailed instructions.
Shell completion setup varies by installation method and shell:If installed via Homebrew: Completions are set up automatically. Make sure you have configured your shell to load Homebrew completions.If installed via Krew: Completions are NOT included. Install completion scripts manually or use a different installation method.Manual setup:See the Installation guide for detailed completion setup instructions.
Recommended installation methods by platform:macOS: Homebrew
brew install kubectx
Debian/Ubuntu: apt
sudo apt install kubectx
Arch Linux: pacman
sudo pacman -S kubectx
Windows: Chocolatey
choco install kubens kubectx
Any platform with kubectl: Krew
kubectl krew install ctx ns
These methods handle dependencies and updates automatically.

​
Interactive Mode Questions

Interactive mode provides a fuzzy search interface for selecting contexts and namespaces.To enable: Install fzf on your system:
# macOS
brew install fzf

# Debian/Ubuntu
sudo apt install fzf

# Arch Linux
sudo pacman -S fzf
Once fzf is installed and in your $PATH, kubectx and kubens will automatically use interactive mode when:
  • No arguments are provided
  • Output is to a terminal (not piped)
Features:
  • Type to fuzzy search
  • Arrow keys to navigate
  • Enter to select
  • Multi-select for deletion (kubectx -d)
There are multiple ways to disable interactive mode:Permanently disable:
export KUBECTX_IGNORE_FZF=1
Add this to your .bashrc, .zshrc, or shell configuration file.Temporarily disable for one command: Pipe the output to another command:
kubectx | cat
kubens | cat
Why disable?
  • Scripting and automation
  • Preference for list view
  • Remote sessions where fzf doesn’t work well
No, interactive mode is designed for human use in terminals. In scripts:
  • Interactive mode is automatically disabled when output is piped
  • Set KUBECTX_IGNORE_FZF=1 to ensure non-interactive behavior
  • Use explicit context/namespace names in scripts
Example script:
#!/bin/bash
export KUBECTX_IGNORE_FZF=1

kubectx production
kubens backend
kubectl apply -f deployment.yaml

​
Usage Questions

Use the rename syntax NEW_NAME=OLD_NAME:
kubectx prod=gke_my-project-123456_us-central1-a_production-cluster
To rename the current context:
kubectx prod=.
This makes long auto-generated context names much easier to work with.
Use the - argument:
# Switch contexts
kubectx production
kubectx staging
kubectx -              # Back to production

# Switch namespaces
kubens backend
kubens frontend
kubens -               # Back to backend
This works similar to cd - in shell navigation.
Yes, provide multiple context names to the delete command:
kubectx -d old-cluster-1 old-cluster-2 old-cluster-3
Or use interactive mode (requires fzf):
kubectx -d
# Use Tab to multi-select contexts
# Press Enter to delete selected
No, kubectx -d only deletes the context entry. The associated cluster and user entries remain in your kubeconfig.What gets deleted:
  • The context entry (mapping between cluster, user, and namespace)
What remains:
  • Cluster entry (server URL, certificate-authority, etc.)
  • User entry (credentials, client certificates, etc.)
To fully remove a cluster, you need to manually edit kubeconfig or use:
kubectl config delete-cluster CLUSTER_NAME
kubectl config delete-user USER_NAME
Use the --force or -f flag:
kubens new-namespace --force
This skips the validation check and sets the namespace even if it doesn’t exist in the cluster. Useful for:
  • Preparing configuration before namespace creation
  • Automation scripts that create namespaces later
  • Working in disconnected environments
kubectx --unset (or -u):
  • Clears the current-context preference
  • Does not delete any context entries
  • Requires --context flag for subsequent kubectl commands
kubectx -u
# current-context is now empty
kubectl get pods --context=minikube  # Must specify context
kubectx -d (delete):
  • Permanently removes context entries from kubeconfig
  • Cannot be undone without re-adding the context
  • If you delete the current context, current-context becomes empty
kubectx -d old-cluster
# Context entry is permanently removed

​
Customization Questions

Use the KUBECTX_CURRENT_FGCOLOR and KUBECTX_CURRENT_BGCOLOR environment variables:
# Blue text on white background
export KUBECTX_CURRENT_FGCOLOR=$(tput setaf 6)
export KUBECTX_CURRENT_BGCOLOR=$(tput setab 7)
Add these to your shell configuration file (.bashrc, .zshrc, etc.) to make them permanent.See tput color codes for available colors.To disable colors entirely:
export NO_COLOR=1
Yes, use kube-ps1, a complementary tool that adds Kubernetes context and namespace information to your shell prompt.
# Install kube-ps1
brew install kube-ps1  # macOS

# Add to .bashrc or .zshrc
source "/usr/local/opt/kube-ps1/share/kube-ps1.sh"
PS1='$(kube_ps1)'$PS1
Your prompt will show:
(⎈ |minikube:default) $
This pairs very well with kubectx and kubens.
kubectx state file:
  • Default: ~/.kube/kubectx
  • Override: $KUBECTX_STATE_DIR/kubectx
  • Contains: Name of the previous context
kubens state files:
  • Default: ~/.kube/kubens/
  • Override: $KUBECTX_STATE_DIR/kubens/
  • Contains: One file per context, each storing the previous namespace for that context
These files are plain text and managed automatically.

​
Troubleshooting

Interactive mode requires fzf. Check if it’s installed and in your PATH:
which fzf
fzf --version
If not installed:
# macOS
brew install fzf

# Debian/Ubuntu
sudo apt install fzf

# Arch Linux
sudo pacman -S fzf
Also check if you’ve disabled it:
echo $KUBECTX_IGNORE_FZF
# If this prints "1", interactive mode is disabled
Tab completion requires proper installation of completion scripts:1. Verify completion scripts are installed:
# For bash
ls $(pkg-config --variable=completionsdir bash-completion)

# For zsh
echo $fpath
# Completion files should be in one of these directories
2. Check your installation method:3. Reload your shell:
exec $SHELL
4. For zsh, you may need:
autoload -U compinit && compinit
For contexts:
# List available contexts
kubectx

# Or use kubectl
kubectl config get-contexts
Make sure the context exists in your kubeconfig. Context names are case-sensitive.For namespaces:
# List available namespaces
kubens

# Or use kubectl
kubectl get namespaces
If the namespace doesn’t exist but you want to set it anyway:
kubens my-namespace --force
This shouldn’t happen. kubectx and kubens modify your kubeconfig file directly, which is persistent.Check if:
  1. You have write permissions to your kubeconfig: 
    ls -l ~/.kube/config
  2. You’re using a custom kubeconfig location: 
    echo $KUBECONFIG
  3. Another process is overwriting your kubeconfig
  4. You’re in a different context than you think: 
    kubectx -c
kubens -c

​
Integration Questions

Yes, but disable interactive mode:
export KUBECTX_IGNORE_FZF=1

kubectx production
kubens backend
kubectl apply -f deployment.yaml
Alternatively, use kubectl config commands which may be more explicit for CI/CD:
kubectl config use-context production
kubectl config set-context --current --namespace=backend
Yes, kubectx and kubens work with the kubeconfig file format, which is standard across all kubectl versions. They are kubectl-version agnostic.They work with:
  • All kubectl versions
  • Any tool that uses kubeconfig (helm, k9s, etc.)
  • Multiple kubeconfig files (via $KUBECONFIG environment variable)
Yes, they respect the $KUBECONFIG environment variable:
# Single kubeconfig
export KUBECONFIG=~/.kube/config

# Multiple kubeconfigs (colon-separated)
export KUBECONFIG=~/.kube/config:~/.kube/config-prod:~/.kube/config-dev
kubectx and kubens will read and write to the merged view of all specified kubeconfig files.

​
Still Have Questions?

If you didn’t find your answer here:
  1. Check the GitHub Issues for similar questions
  2. Review the command reference for detailed usage
  3. Open a new issue on GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us