Skip to content
Get packs

Guide · Open source

How to use Pure: install the zsh prompt and set it up

Updated · written with AI from the project's own documentation and checked against our catalogue data

Pure is a minimal, fast prompt for the zsh shell. It shows your current folder, your git branch, and arrows when local commits are not yet pushed or pulled. This guide walks through installing it, turning it on, and adjusting the options that matter.

Puresindresorhus/pure · ★ 14.5k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have zsh 5.2 or newer and Git 2.15.2 or newer.
  2. 2Install the package. Run npm install --global pure-prompt, or brew install pure if you use Homebrew.
  3. 3Fix fpath if needed. If prompt -l does not list pure, add the fpath line from the README to your .zshrc before promptinit.
  4. 4Enable the prompt. Add autoload -U promptinit; promptinit and prompt pure to your .zshrc.
  5. 5Open a new shell. Restart your terminal or run zsh so the .zshrc changes load.
  6. 6Tune options. Set environment variables or zstyle lines to turn features on or off.

Check the requirements first

Pure needs Git 2.15.2 or newer and zsh 5.2 or newer. The README says older zsh versions are known to work but are not recommended.

Pure is a zsh-only prompt. It will not work in bash or fish.

  • Git 2.15.2+
  • ZSH 5.2+
  • npm, if you use the npm install route

Install Pure with npm or Homebrew

The simplest route is npm. Note that the README says to use npm, not yarn. If the prompt does not appear in the list after installing, add an fpath line to your .zshrc.

If you use Homebrew, install the package with brew. If you installed zsh with Homebrew, you may not need the extra fpath line. If you are not using Homebrew's zsh, add the site-functions path to your .zshrc.

  • npm: run the global install, then check whether prompt -l lists pure.
  • Homebrew: install the pure formula.
  • Manual: clone the repo and add its path to fpath in $HOME/.zshrc.
npm install --global pure-prompt brew install pure fpath+=("$(npm root -g)/pure-prompt")

Turn Pure on in your .zshrc

Pure is enabled through zsh's prompt system. Load promptinit, then select pure. Put these lines in your .zshrc so the prompt loads each time you open a shell.

# .zshrc autoload -U promptinit; promptinit prompt pure

Configure Pure with environment variables and zstyle

Pure reads a set of environment variables for symbols and timing. Defaults include a 5 second threshold for showing command run time (PURE_CMD_MAX_EXEC_TIME) and the prompt symbol (PURE_PROMPT_SYMBOL). Set any of these in your .zshrc before the prompt loads.

Several features are off by default and must be turned on with zstyle. Examples include git stash status, detailed dirty indicators (separate *, +, and ? marks), and Node.js version display. Git, virtualenv and nix-shell integration are on by default and can be turned off.

  • PURE_CMD_MAX_EXEC_TIME: default 5 seconds
  • PURE_PROMPT_SYMBOL: default ❯
  • zstyle :prompt:pure:git:dirty detailed yes (off by default)
  • zstyle :prompt:pure:environment:node_version show yes (off by default)
  • zstyle :prompt:pure:host show no (hostname shown only over SSH or in a container by default)
zstyle :prompt:pure:git:stash show yes zstyle :prompt:pure:git:dirty detailed yes zstyle :prompt:pure:environment:node_version show yes

Add your own segments with prompt_pure_precustom

Pure has a hook for custom content. Define a function called prompt_pure_precustom in your .zshrc after prompt pure. Write text into psvar[22] for a prefix or psvar[23] for a suffix.

The hook runs every time the prompt renders, including async redraws, so keep it fast. For slow commands, cache the value in a precmd hook and read the cached value in the prompt function.

  • psvar[22]: custom prefix, shown before built-in segments
  • psvar[23]: custom suffix, shown after built-in segments
  • Colors: zstyle :prompt:pure:custom:prefix color cyan
my_kube_context= my_precmd() { my_kube_context=$(kubectl config current-context 2>/dev/null) } add-zsh-hook precmd my_precmd prompt_pure_precustom() { psvar[22]=$my_kube_context psvar[23]=$(date +%H:%M) }

Choose colors and symbols

Colors can be a number from your terminal's color index, one of nine names (black, red, green, yellow, blue, magenta, cyan, white, default), or a hex value like #424242. Hex values need a terminal with 24-bit color, or the zsh/nearcolor module loaded.

Each color is set with zstyle using a pattern such as :prompt:pure:git:branch. The README lists defaults for each part, for example git:dirty uses 218 and execution_time uses yellow.

What people use it for

  • Keep a clean view of your current folder and git branch while working in several repositories.
  • See at a glance whether a repo has uncommitted changes or unpushed commits.
  • Show the Kubernetes context or current time in the prompt using the custom prefix or suffix hook.
  • Show the Node.js major version inside projects that have a package.json, by enabling the node_version option.

Frequently asked questions

Does Pure work with bash or fish?

No. The README describes Pure as a zsh-only prompt, and it will not work in bash or fish. You need zsh 5.2 or newer.

How do I install Pure?

You can install it with npm using npm install --global pure-prompt, or with Homebrew using brew install pure. You can also clone the repo manually and add its path to fpath. The README says to use npm, not yarn.

Is Pure free to use?

Pure is released under the MIT licence, as listed on its project page. The licence permits use, which is why it is commonly installed without cost.

Why doesn't prompt -l list pure after installing?

The README says to add the npm global package folder to fpath in your .zshrc before promptinit. Use the line fpath+=("$(npm root -g)/pure-prompt") and then open a new shell.

How does Pure compare to Powerlevel10k, Starship or Oh My Zsh?

Pure focuses on a simple, minimal prompt that is easy to read. Powerlevel10k, Starship and Oh My Zsh are listed as comparable projects; choose based on how many built-in segments you want by default. Pure keeps many extras off unless you enable them.

Why is my git status slow or not updating?

Pure checks git status asynchronously, and the README notes that dirty checks are delayed when git status takes more than 5 seconds. You can change PURE_GIT_DELAY_DIRTY_CHECK, and PURE_GIT_UNTRACKED_DIRTY can exclude untracked files on large repos.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Pure suits developers who use zsh and want a clean, readable prompt that shows git branch and status at a glance. If you use bash or fish, or want many segments enabled out of the box, pick another prompt such as Starship or Powerlevel10k.

Install options & downloads