Skip to main content
Shell completion makes kubectx and kubens even faster by providing tab-completion for context and namespace names. This guide covers setup for Bash, Zsh, and Fish shells.

​
Bash Completion

​
Installation

The completion scripts are located in the completion/ directory of the kubectx repository.
1

Locate completion scripts

If installed via package manager, completion scripts should be automatically installed. Otherwise:
# Clone the repository
git clone https://github.com/ahmetb/kubectx.git
cd kubectx/completion
2

Source the completion scripts

Add to your ~/.bashrc or ~/.bash_profile:
# kubectx completion
source /path/to/kubectx/completion/kubectx.bash

# kubens completion
source /path/to/kubectx/completion/kubens.bash
3

Reload your shell

source ~/.bashrc

​
Package Manager Installation

# Completion is automatically set up
brew install kubectx

# Ensure bash-completion is installed
brew install bash-completion@2

# Add to ~/.bash_profile or ~/.bashrc:
export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"

​
Usage

Once configured, use Tab to complete context names: 
kubectx mi<TAB>
# Expands to:
kubectx minikube

kubectx gke_<TAB><TAB>
# Shows all contexts starting with gke_:
gke_project_us-central1_dev
gke_project_us-central1_staging  
gke_project_us-central1_prod
The - shorthand is also completed: 
kubectx -<TAB>
# Completes to:
kubectx -

​
Zsh Completion

​
Installation

1

Locate completion scripts

Zsh completion scripts use the _ prefix:
ls -l completion/_kubectx.zsh
ls -l completion/_kubens.zsh
2

Copy to fpath location

Copy completion scripts to a directory in your $fpath:
# Create completion directory if it doesn't exist
mkdir -p ~/.zsh/completion

# Copy completion files
cp completion/_kubectx.zsh ~/.zsh/completion/_kubectx
cp completion/_kubens.zsh ~/.zsh/completion/_kubens
3

Update ~/.zshrc

Add the completion directory to your fpath before loading compinit:
# Add to ~/.zshrc
fpath=(~/.zsh/completion $fpath)

autoload -U compinit
compinit
4

Reload your shell

source ~/.zshrc

​
Oh My Zsh Installation

If you use Oh My Zsh: 
# Copy to custom plugins directory
mkdir -p ~/.oh-my-zsh/custom/completions
cp completion/_kubectx.zsh ~/.oh-my-zsh/custom/completions/_kubectx
cp completion/_kubens.zsh ~/.oh-my-zsh/custom/completions/_kubens

# Reload
source ~/.zshrc

​
Package Manager Installation

# Install kubectx
brew install kubectx

# Completion is automatically set up via brew's fpath integration
# Ensure this is in your ~/.zshrc:
if type brew &>/dev/null; then
  FPATH=$(brew --prefix)/share/zsh/site-functions:$FPATH
  autoload -U compinit
  compinit
fi

​
Features

Zsh completion includes:
  • Context name completion
  • Support for - (switch to previous)
  • Support for -d flag with context names
  • Dynamic context list from kubectl config get-contexts
kubectx <TAB>
# Shows all available contexts

kubectx -d <TAB>
# Shows all contexts that can be deleted

kubens <TAB>  
# Shows all namespaces in current context

​
Fish Completion

​
Installation

1

Locate completion scripts

Fish completion scripts:
ls -l completion/kubectx.fish
ls -l completion/kubens.fish
2

Copy to Fish completions directory

# Create completions directory if it doesn't exist
mkdir -p ~/.config/fish/completions

# Copy completion files
cp completion/kubectx.fish ~/.config/fish/completions/
cp completion/kubens.fish ~/.config/fish/completions/
3

Reload completions

# Completions are loaded automatically
# Or manually reload:
fish_update_completions

​
Package Manager Installation

# Install kubectx
brew install kubectx

# Completions are automatically installed to:
# $(brew --prefix)/share/fish/vendor_completions.d/

​
Usage

Fish provides rich completion descriptions: 
kubectx <TAB>
# Shows contexts with descriptions if available

kubectx -<TAB>
# Shows:
-  (switch to the previous namespace in this context)

​
Alias Completion

If you use aliases for kubectx and kubens, you need to configure completion for the aliases as well.

​
Bash

# Add to ~/.bashrc
alias kctx='kubectx'
alias kns='kubens'

# Enable completion for aliases
complete -F _kube_contexts kctx
complete -F _kube_namespaces kns

​
Zsh

# Add to ~/.zshrc
alias kctx='kubectx'
alias kns='kubens'

# Enable completion for aliases
compdef kctx=kubectx
compdef kns=kubens

​
Fish

# Add to ~/.config/fish/config.fish
alias kctx='kubectx'
alias kns='kubens'

# Fish automatically handles completion for aliases

​
kubectl Plugin Completion

If you’re using kubectx/kubens as kubectl plugins: 
# Completion works automatically through kubectl
kubectl ctx <TAB>
kubectl ns <TAB>
kubectl’s built-in completion handles plugin completion.
Make sure kubectl completion is enabled. See kubectl completion docs for setup.

​
Verifying Completion

Test that completion is working:
1

Test kubectx completion

kubectx <TAB>
# Should show list of contexts
2

Test kubens completion

kubens <TAB>
# Should show list of namespaces
3

Test flag completion

kubectx -<TAB>
# Should show: - (switch to previous context)

​
Troubleshooting

​
Completion Not Working

If tab completion isn’t working:
1

Check if completion is loaded

# Check if completion function exists
type _kube_contexts
# Should show: _kube_contexts is a function
2

Verify shell integration

Make sure bash-completion or zsh completion system is enabled:
# Bash: check if bash-completion is loaded
type _init_completion

# Zsh: check if compinit is called
whence compinit
3

Reload shell configuration

exec $SHELL

​
Completions Out of Date

If new contexts/namespaces don’t appear in completion: 
# Completions are generated dynamically
# They call: kubectl config get-contexts

# Verify kubectl can list contexts:
kubectl config get-contexts --output=name

# If this works, completion should work too

​
Permission Errors

If you see permission errors: 
# Make sure completion files are readable
chmod +r ~/.zsh/completion/_kubectx
chmod +r ~/.config/fish/completions/kubectx.fish

​
Advanced Configuration

​
Custom Completion Behavior

You can modify the completion scripts to customize behavior. For example, in Bash: 
# Custom completion that excludes certain contexts
_kube_contexts_filtered()
{
  local curr_arg;
  curr_arg=${COMP_WORDS[COMP_CWORD]}
  local contexts=$(kubectl config get-contexts --output='name' | grep -v 'test')
  COMPREPLY=( $(compgen -W "- $contexts" -- $curr_arg ) );
}

complete -F _kube_contexts_filtered kubectx

​
Completion Performance

For large kubeconfig files, completion might be slow. Consider:
  1. Caching contexts (not implemented by default)
  2. Using fzf interactive mode instead of tab completion
  3. Splitting kubeconfig into smaller files
Interactive mode with fzf is often faster than tab completion for large context lists.

​
Next Steps

Interactive Mode

Learn about fzf integration for visual selection

kubectx Commands

Master all kubectx commands and features

Build docs developers (and LLMs) love

Get started for freeTalk to us