kube-ps1: Kubernetes Context and Namespace in Your Shell Prompt

What kube-ps1 solves for people who live in kubectl

kubectl keeps its current context and namespace in a kubeconfig file, not in your shell. Nothing in a normal prompt tells you which of those contexts is active, so the failure mode is running a command against staging while you believe you are on production. kube-ps1 closes that gap by putting the active context and namespace into the prompt string itself. The README describes it as a script that adds the current Kubernetes context and namespace configured on kubectl to your Bash, Zsh, or Fish prompt. The intended audience is anyone who runs kubectl interactively: platform engineers, SREs, and developers with more than one cluster in their kubeconfig. The repository topics list bash, containers, kubectl, kubernetes, kubernetes-helper, prompts, sre and zsh, which matches that audience. It is a prompt decoration, not a safety control. It shows you where you are; it does not stop you from running the wrong command.

How the prompt string is assembled

kube-ps1 is a shell function, not a background process. You source kube-ps1.sh (or kube-ps1.fish for fish), and your prompt then calls kube_ps1 on every render. The default layout documented in the README is (symbol|context:namespace). The symbol defaults to the Unicode helm character ⎈ (\u2388), the separator between symbol and context is |, the divider between context and namespace is :, and the prefix and suffix are ( and ). If no current-context is set, the function returns (symbol|N/A:N/A), which is a visible signal rather than a silent blank. If neither kubectl nor the configured binary is available, the prompt prints (symbol|BINARY-N/A:N/A). Every piece of that string is controlled by environment variables read at call time: KUBE_PS1_BINARY defaults to kubectl, KUBE_PS1_NS_ENABLE defaults to true, KUBE_PS1_SYMBOL_ENABLE defaults to true, KUBE_PS1_SYMBOL_COLOR defaults to blue, and KUBE_PS1_HIDE_IF_NOCONTEXT defaults to false. Setting KUBE_PS1_NS_ENABLE to false also disables KUBE_PS1_DIVIDER, and setting KUBE_PS1_SYMBOL_ENABLE to false also disables KUBE_PS1_SEPARATOR. Three variables accept user-supplied functions: KUBE_PS1_CLUSTER_FUNCTION, KUBE_PS1_NAMESPACE_FUNCTION and KUBE_PS1_CTX_COLOR_FUNCTION, which lets you rewrite the displayed cluster or namespace text, or color the context by name. That is the whole architecture: read kubeconfig state through the binary, format it, return a string.

Installing kube-ps1 and getting a first prompt

The README lists several install paths. On macOS, Homebrew is the shortest. This installs the package, and you then source the installed script from your shell rc file.

brew update
brew install kube-ps1

If you already use oh-my-zsh, kube-ps1 ships as a bundled plugin. Add it to the plugins array in ~/.zshrc and call kube_ps1 from PROMPT or RPROMPT. The README gives exactly this snippet:

plugins=(
  kube-ps1
)
PROMPT='$(kube_ps1)'$PROMPT # or RPROMPT='$(kube_ps1)'

Without a package manager, clone the repository and source the script directly. For zsh, the README shows sourcing kube-ps1.sh and prepending the function call to PROMPT:

source /path/to/kube-ps1.sh
PROMPT='$(kube_ps1)'$PROMPT # or RPROMPT='$(kube_ps1)'

For bash, the same source line goes into ~/.bashrc, but the prompt is built with PS1 instead:

source /path/to/kube-ps1.sh
PS1='[\u@\h \W $(kube_ps1)]\$ '

Fish users must source kube-ps1.fish rather than kube-ps1.sh. The README puts the source line in ~/.config/fish/config.fish and wraps the call inside a fish_prompt function:

source /path/to/kube-ps1.fish

function fish_prompt
    echo -n (kube_ps1) ' '
    # your existing prompt here
end

After reloading your shell, the prompt should show something like (⎈|my-context:default). If it shows (⎈|N/A:N/A), no current-context is set. If it shows (⎈|BINARY-N/A:N/A), kubectl is not on PATH or KUBE_PS1_BINARY points at a missing binary. To turn the segment off in the current shell run kubeoff; kubeoff -g disables it globally. kubeon and kubeon -g reverse those. The per-shell setting takes precedence over the global one for the current session.

Where kube-ps1 gets in the way

The prompt has no memory. It renders the context that kubectl reports at that moment, so the moment you run kubectl config use-context, the display changes. That is the intended behavior, but it means kube-ps1 cannot warn you that a command you already typed was aimed at the wrong cluster. The README does not document any confirmation, guard or dry-run behavior. There is also a rendering cost: the function runs on every prompt draw, and it shells out to the configured binary to read the current context. On slow or remote kubeconfig setups this can be noticeable, and the README does not document caching or a timeout. The symbol is a real portability problem. The default ⎈ is a Unicode character, and the custom options img, oc and k8s use glyphs that require a Nerd Fonts patched font. The README states plainly that if the font is not properly installed and the glyph is unavailable, you will see an empty set of brackets or similar. Finally, kube-ps1 shows one context. If your workflow spans several clusters in parallel terminals, the prompt tells you about the one in that shell and nothing about the others. Teams that need a persistent, always-visible cluster indicator across a session should look at the tmux port instead.

kube-ps1 versus kubectx and kubens

The README points at kubectx and kubens as complementary tools for fast switching between clusters and namespaces. The difference in approach matters. kubectx and kubens are switchers: they change the current context or namespace, and they are invoked deliberately when you want to move. kube-ps1 is a reporter: it never changes state, it only reads what kubectl already has and prints it. In practice you want both, and the README treats them that way rather than as substitutes. If you had to pick one, kubectx solves the problem of typing long context names; kube-ps1 solves the problem of not knowing which context is active. They fail in opposite directions. A switcher without a prompt indicator leaves you guessing after the switch. An indicator without a switcher leaves you typing full context names but always aware of where you are. For OpenShift users there is a related configuration detail: kube-ps1 can drive the oc binary instead of kubectl by setting KUBE_PS1_BINARY=oc, which the README documents alongside the brew install openshift-cli path.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-07, so the project has seen recent commits. Release cadence is slow and uneven: v0.8.0 in November 2022, v0.9.0 in June 2024, and v1.0.0 in May 2026. Anyone tracking versions should read that as a low-churn project rather than a fast-moving one, and should not expect frequent breaking changes. Upgrades are cheap in the common case because the interface is environment variables and a sourced file: replacing kube-ps1.sh and reloading the shell is usually the whole operation. The cost that does exist is configuration drift. If you have set KUBE_PS1_SYMBOL_CUSTOM, KUBE_PS1_BINARY or any of the color and function variables across a team, those settings live in each user's rc file, not in the repository, so a version bump will not migrate them for you. The project is licensed Apache-2.0, which permits commercial and internal use and requires preserving the licence and notices; the LICENSE file is at the repository root. That is a description of the licence, not legal advice, and anyone redistributing a modified copy should read the terms themselves.

Editorial conclusion

Adopt kube-ps1 if you switch kubectl contexts often and want the active cluster visible in every terminal before you run anything. Skip it if you only ever touch one cluster, or if you need the prompt to display several contexts at once, which the documented layout does not do. Before rolling it out, source kube-ps1.sh in a scratch shell, confirm your font renders the default ⎈ symbol or set KUBE_PS1_SYMBOL_CUSTOM=img, and check that kubeoff -g and kubeon -g behave as documented on your shell version.

Frequently asked questions

Official sources

1. Issues
2. jonmosco/kube-ps1 on GitHub
3. License: Apache-2.0
4. README
5. Releases