Skip to main content
kubectx is a powerful command-line tool for switching between Kubernetes contexts (clusters) quickly and efficiently.

​
Overview

The kubectx command can be invoked as either:
  • kubectx - standalone binary
  • kubectl ctx - as a kubectl plugin
All commands and examples below work with either invocation method.

​
Commands

​
List Contexts

​
kubectx
command
Lists all available contexts from your kubeconfig file.
Usage: 
kubectx
Behavior:
  • If fzf is installed and output is to a terminal, launches interactive fuzzy search mode
  • Otherwise, displays a list of all contexts with the current context highlighted
  • The current context is marked with a different color (customizable via environment variables)
Example: 
$ kubectx
minikube
oregon
gke_project_us-west1_cluster-1

​
Switch Context

​
kubectx <NAME>
command
Switches to the specified context.
Parameters:
  • <NAME> - The name of the context to switch to
Usage: 
kubectx <NAME>
Example: 
$ kubectx minikube
Switched to context "minikube".

​
Switch to Previous Context

​
kubectx -
command
Switches back to the previously active context.
Usage: 
kubectx -
Behavior:
  • Maintains a state file tracking the previous context
  • Allows quick toggling between two contexts
  • Similar to cd - in shell navigation
Example: 
$ kubectx oregon
Switched to context "oregon".

$ kubectx minikube
Switched to context "minikube".

$ kubectx -
Switched to context "oregon".

​
Show Current Context

​
kubectx --current
command
Displays the name of the current active context.
Aliases: -c, --current Usage: 
kubectx --current
kubectx -c
Example: 
$ kubectx -c
minikube
Use Cases:
  • Shell scripting and automation
  • Display in shell prompts (PS1)
  • CI/CD pipeline validation

​
Rename Context

​
kubectx <NEW_NAME>=<NAME>
command
Renames an existing context to a new name.
Syntax: 
kubectx <NEW_NAME>=<NAME>
kubectx <NEW_NAME>=.        # Rename current context
Parameters:
  • <NEW_NAME> - The desired new name for the context
  • <NAME> - The existing context name to rename, or . for current context
Behavior:
  • If the new name already exists, it will be overwritten with a warning
  • If renaming the current context, the current-context preference is updated
  • Does not affect the cluster or user entries in kubeconfig
Examples: 
# Rename a specific context
$ kubectx dublin=gke_ahmetb_europe-west1-b_dublin
Context "gke_ahmetb_europe-west1-b_dublin" renamed to "dublin".

# Rename the current context
$ kubectx prod=.
Context "minikube" renamed to "prod".

​
Unset Current Context

​
kubectx --unset
command
Removes the current-context preference from kubeconfig.
Aliases: -u, --unset Usage: 
kubectx --unset
kubectx -u
Behavior:
  • Clears the current-context field in kubeconfig
  • kubectl commands will require explicit --context flag afterward
  • Does not delete any context entries
Example: 
$ kubectx --unset
Active context unset for kubectl.

​
Delete Context

​
kubectx -d <NAME> [<NAME>...]
command
Deletes one or more context entries from kubeconfig.
Aliases: -d Syntax: 
kubectx -d <NAME> [<NAME>...]
kubectx -d .                    # Delete current context
Parameters:
  • <NAME> - One or more context names to delete
  • . - Special value to delete the current context
Behavior:
  • Can delete multiple contexts in a single command
  • If fzf is installed and no names provided, launches interactive deletion mode
  • Does not delete the associated user or cluster entries
  • Warns if you delete the current context
Examples: 
# Delete a specific context
$ kubectx -d old-cluster
Deleted context old-cluster.

# Delete multiple contexts
$ kubectx -d context1 context2 context3
Deleted context context1.
Deleted context context2.
Deleted context context3.

# Delete current context
$ kubectx -d .
You deleted the current context. Use "kubectx" to select a new context.
Deleted context minikube.

# Interactive deletion (with fzf)
$ kubectx -d
# Opens fzf for selection

​
Display Help

​
kubectx --help
command
Shows usage information and command reference.
Aliases: -h, --help Usage: 
kubectx --help
kubectx -h

​
Display Version

​
kubectx --version
command
Shows the version of kubectx.
Aliases: -V, --version Usage: 
kubectx --version
kubectx -V

​
Interactive Mode

When fzf is installed and stdout is a terminal, kubectx launches interactive mode for certain commands:

​
Interactive Context Selection

Running kubectx without arguments opens an interactive fuzzy finder: 
$ kubectx
# Opens fzf with list of contexts
# Type to filter, use arrow keys to select
# Press Enter to switch to selected context

​
Interactive Context Deletion

Running kubectx -d without context names opens interactive deletion: 
$ kubectx -d
# Opens fzf with list of contexts
# Select contexts to delete (multi-select with Tab)
# Press Enter to confirm deletion

​
Disabling Interactive Mode

To disable fzf integration: 
export KUBECTX_IGNORE_FZF=1
Or pipe output to another command: 
kubectx | cat    # Forces non-interactive mode

​
Environment Variables

​
Color Customization

​
KUBECTX_CURRENT_FGCOLOR
string
Foreground color for the current context indicator.
​
KUBECTX_CURRENT_BGCOLOR
string
Background color for the current context indicator.
Usage: 
export KUBECTX_CURRENT_FGCOLOR=$(tput setaf 6)  # blue text
export KUBECTX_CURRENT_BGCOLOR=$(tput setab 7)  # white background
Refer to tput color codes for color values.

​
Disable Colors

​
NO_COLOR
string
Disables all color output when set to any value.
Usage: 
export NO_COLOR=1
Follows the NO_COLOR standard.

​
Disable fzf Integration

​
KUBECTX_IGNORE_FZF
string
Disables interactive mode with fzf when set to 1.
Usage: 
export KUBECTX_IGNORE_FZF=1

​
Exit Codes

CodeDescription
0Success
1Error occurred (invalid context, file error, etc.)

​
Shell Completion

kubectx supports tab completion for:
  • bash
  • zsh
  • fish
Completion scripts are included with most installation methods. See the Installation guide for details on enabling completion for your shell.

​
Integration with kubectl

When installed as a kubectl plugin via Krew, use: 
kubectl ctx              # instead of kubectx
kubectl ctx minikube     # switch context
kubectl ctx --current    # show current

​
State Management

kubectx stores the previous context in a state file to enable the kubectx - functionality:
  • Location: ~/.kube/kubectx
  • Format: Plain text file containing the name of the previous context
  • Automatic: Created and managed automatically

​
Common Use Cases

​
Quick Context Switching

Switch between development and production: 
kubectx dev
# Do some work
kubectx prod
# Check production
kubectx -      # Back to dev

​
Simplify Long Context Names

Rename lengthy auto-generated names: 
kubectx prod=gke_my-project-123456_us-central1-a_production-cluster
kubectx dev=gke_my-project-123456_us-central1-a_development-cluster

​
Clean Up Old Contexts

Remove contexts for deleted clusters: 
kubectx -d old-cluster-1 old-cluster-2 old-cluster-3

​
Scripting and Automation

Save current context before switching: 
#!/bin/bash
CURRENT=$(kubectx -c)
kubectx staging
# Perform operations
kubectx "$CURRENT"  # Restore original context

​
Notes

  • Context deletion does not remove the associated cluster and user entries from kubeconfig
  • Renaming a context only changes the context entry name, not the cluster or user it references
  • The kubectx - command requires at least one previous context switch in the current session

Build docs developers (and LLMs) love

Get started for freeTalk to us