# Pure: a minimal ZSH prompt that keeps git checks off the critical path

> Pure is a ZSH prompt theme distributed as pure-prompt on npm and as the pure Homebrew formula. Its selling point is not decoration but the fact that the expensive parts of a git-aware prompt run asynchronously, so the prompt redraws before the network check finishes.

**sindresorhus/pure** — Pretty, minimal and fast ZSH prompt

- Repository: https://github.com/sindresorhus/pure
- Stars: 14,434 · Forks: 1,006
- Language: Shell
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/sindresorhus-pure

## The problem Pure targets: a git-aware prompt that does not make you wait

A prompt that reports git state has to run git commands before it can draw itself. On a large repository, or on a branch whose remote has moved, that work happens between you pressing Enter and the next prompt appearing. The README frames the project as a reaction to prompts that are "cluttered, ugly and slow", and the design decisions follow from that complaint rather than from a feature list.

The intended user is someone who lives in ZSH, works inside git repositories most of the day, and does not want the prompt to become a status dashboard. Username and host are hidden unless you are in an SSH session or a container. The current path is pushed into the terminal title instead of being repeated on the prompt line. Command execution time only appears when a command exceeds PURE_CMD_MAX_EXEC_TIME, which defaults to 5 seconds. Nothing is displayed that the session does not currently need, and that restraint is the actual product.

## How the asynchronous git check works and what it costs

The repository ships pure.zsh and async.zsh at the top level, with async.zsh also exposed as async and pure.zsh exposed as prompt_pure_setup in the published package. The package.json prepack script copies pure.zsh to prompt_pure_setup and async.zsh to async, which is how the files end up under the names ZSH expects to find on fpath.

The README states that the unpushed and unpulled commit check is done asynchronously, and the async file is what makes that possible. Instead of blocking the prompt on a network-facing check, Pure draws the prompt and lets the git comparison resolve afterwards, then redraws. That is the mechanism behind the claim in the README that the up and down arrows indicate unpushed and unpulled commits, and it is the reason the arrows can appear a moment after the prompt itself.

The cost of that design is visible in the options table. PURE_GIT_DELAY_DIRTY_CHECK defaults to 1800 seconds and exists because git status can take more than 5 seconds, at which point Pure backs off rather than paying that price on every redraw. PURE_GIT_UNTRACKED_DIRTY defaults to 1, meaning untracked files count toward the dirty indicator, and the README calls out large repos such as WebKit as the case where you would turn that off. PURE_GIT_PULL defaults to 1 and controls whether Pure checks whether the current remote has been updated. These are all ways of trading prompt freshness for responsiveness, and the defaults lean toward responsiveness.

## Installing Pure with npm or Homebrew and taking it for a first run

There are three documented installation paths. The npm route is the one the README puts first, and it requires npm rather than yarn. The package name is pure-prompt, not pure.

```bash
npm install --global pure-prompt
```

After that, the README says to check whether the prompt is visible to ZSH with prompt -l. If pure does not appear in that list, the fix is to add the global npm root to fpath before promptinit runs.

```bash
fpath+=("$(npm root -g)/pure-prompt")
```

The Homebrew route installs a formula named pure, which is a different identifier from the npm package name, so it is easy to confuse the two.

```bash
brew install pure
```

If your ZSH is not the Homebrew build, the README requires you to add the Homebrew site-functions directory to fpath yourself, using the output of brew --prefix rather than a hardcoded path. The manual route clones the repository into a directory of your choosing and appends that directory to fpath.

```bash
mkdir -p "$HOME/.zsh"
git clone https://github.com/sindresorhus/pure.git "$HOME/.zsh/pure"
```

Whichever route you take, activation is the same three lines in .zshrc. The first two initialize ZSH's prompt system if nothing else has, and the third selects Pure.

```bash
# .zshrc
autoload -U promptinit; promptinit
prompt pure
```

When it works, you get a single prompt character, a path, and a git segment that fills in shortly after the prompt is drawn. If the character stays white after a failing command, or the git segment never appears inside a repository, the prompt is not the one being rendered.

## Turning features on with zstyle, and the ones that are off by default

Pure's defaults are deliberately sparse, and the README documents a second configuration surface beyond environment variables. Several capabilities exist but require an explicit zstyle line. Git stash status needs zstyle :prompt:pure:git:stash show yes. Detailed dirty indicators, which separate unstaged, staged and untracked changes into * , + and ? instead of a single asterisk, need zstyle :prompt:pure:git:dirty detailed yes. Dimming the path separators needs zstyle :prompt:pure:path:separator dim yes. Node.js version display needs zstyle :prompt:pure:environment:node_version show yes, and its symbol can be changed with zstyle :prompt:pure:environment:node_version symbol.

Others are on by default and can be turned off. Git integration itself is disabled with zstyle :prompt:pure:git show no. The nix-shell segment is on by default and disabled with zstyle :prompt:pure:environment:nix-shell show no. The virtualenv and Conda segment is likewise on by default and disabled with zstyle :prompt:pure:environment:virtualenv show no. Hostname display in an SSH session can be suppressed while keeping the username via zstyle :prompt:pure:host show no, and terminal title management can be handed back to you with zstyle :prompt:pure:title show no.

There is also a hook. Defining prompt_pure_precustom after prompt pure lets you write into psvar[22] as a prefix and psvar[23] as a suffix, both rendered on the preprompt line. The README warns that this function runs on every render, including asynchronous redraws, and tells you to cache expensive work in a precmd hook instead. That warning is the honest part of the feature: a naive kubectl call inside prompt_pure_precustom would reintroduce exactly the latency the project was built to avoid.

## Where Pure is the wrong choice

Pure is a ZSH prompt. The README lists ZSH 5.2 or newer and Git 2.15.2 or newer as requirements, and notes that older ZSH versions are known to work but are not recommended, which is a polite way of saying the compatibility surface is not maintained. If your team standardizes on fish, bash or PowerShell, or if you want the same prompt on a remote server and a Windows workstation, Pure cannot help you, because there is nothing to install outside ZSH.

There is also a configuration ceiling. The zstyle switches and the psvar hook give you prefix and suffix segments, but the README does not document replacing the built-in segments themselves. If you want a prompt with a language runtime version, a cloud context, a Kubernetes namespace and a timer all rendered in your own layout, you will spend more time working around Pure's structure than writing a prompt from scratch. Pure's own README says it makes an excellent starting point for a custom prompt, which is an admission that the end state for many users is a fork rather than a configuration.

Finally, the asynchronous git check is not free of surprises. Because the arrows arrive after the prompt is drawn, a scripted workflow that reads the prompt text immediately will not see them. The README does not document any synchronous mode for that check.

## Pure compared with Starship, and what the difference actually is

The obvious alternative is Starship, which people search for alongside Pure as "Zsh pure vs starship". The difference is architectural, not cosmetic. Starship is a cross-shell prompt binary: one configuration drives bash, ZSH, fish and others, and the prompt is produced by an external program. Pure is a set of ZSH functions loaded onto fpath, with no compiled binary and no separate configuration language. There is no starship.toml equivalent here; configuration is environment variables and zstyle calls inside .zshrc.

That has practical consequences. A Starship setup travels with you to a fish shell or a PowerShell session; a Pure setup does not leave ZSH. On the other hand, Pure has no binary to install and no per-prompt process spawn for the prompt itself, which is a plausible reason to prefer it on a machine where you want the prompt to be part of the shell rather than a program the shell calls. The repository's own test script runs zsh tests/test.zsh, so the project's testing story is a ZSH script rather than a compiled test suite, consistent with that design.

If you are choosing between them, the deciding question is whether the prompt needs to exist outside ZSH. If yes, Pure is the wrong tool regardless of how it looks. If no, Pure's async git handling and its small configuration surface are the relevant comparison points, and you should judge them against your own repositories rather than against screenshots.

## Maintenance, licence and what upgrading involves

The repository is not archived, and the last push was on 2026-09-19. Releases are frequent enough to matter: v1.28.1 on 2026-05-20, v1.28.2 on 2026-07-13, and v1.28.3 on 2026-07-16. The package.json version field matches v1.28.3, and the version script rewrites prompt_pure_state[version] inside pure.zsh and stages it, so the version string lives in the prompt source rather than being read from npm at runtime.

Upgrading through npm or Homebrew replaces the files on fpath, and because the configuration lives in your .zshrc, an upgrade does not touch it. The risk sits in the opposite direction: options that were added between releases are inert until you add the zstyle line, so an upgrade can change rendering without changing anything you wrote. Reviewing the release notes before upgrading is the only way to catch a changed default.

The licence is MIT, stated in both the README badge area and the package.json license field. MIT is permissive and permits commercial use and modification; the practical obligation is retaining the copyright notice and permission text when you redistribute the code. Pure is a prompt you load into your own shell, so redistribution is usually not in play, but if you vendor pure.zsh into an internal dotfiles repository that ships to other machines, the licence text needs to travel with it. This is a description of the licence terms, not legal advice.

## Conclusion

Adopt Pure if you already run ZSH 5.2 or newer with Git 2.15.2 or newer, you want a prompt that stays quiet outside a repository, and you are willing to keep the prompt configuration in .zshrc rather than in a cross-shell tool. Skip it if you need one prompt across bash, fish and PowerShell, or if you want a large gallery of ready-made themes; Pure is one prompt with zstyle switches, not a theme framework. Before committing, verify three things on your own machine: that prompt -l lists pure after installation, that the prompt character turns red when a command exits non-zero, and that the up and down git arrows appear only after the asynchronous check completes rather than blocking the shell.

## FAQ

### Do I really need Oh My Zsh to use Pure?

No. The README's install instructions are npm, Homebrew or a manual clone, and activation is autoload -U promptinit; promptinit followed by prompt pure. Oh My Zsh is not mentioned as a requirement anywhere in the installation steps.

### What is the best prompt for Zsh?

That depends on what you are optimizing for, and the README only describes Pure's own trade-offs: it hides username and host outside SSH and containers, shows command time only past a threshold, and runs the unpushed and unpulled commit check asynchronously. If those priorities match yours, Pure is a candidate; the README does not rank it against other prompts.

### What is the most popular Zsh theme?

The repository does not report popularity, and star or download figures are not part of the README. What is documented is that Pure is distributed as the pure-prompt npm package and the pure Homebrew formula, and that its releases run through v1.28.3.

### What are some good alternatives to Zsh?

Pure is a ZSH prompt and does not replace the shell, so alternatives to ZSH itself are outside what this project covers. Within the prompt space, the README does not name competing prompts; the cross-shell comparison point is that Pure loads onto ZSH fpath and does not run outside ZSH.

## Sources

- [Issues](https://github.com/sindresorhus/pure/issues)
- [License: MIT](https://github.com/sindresorhus/pure/blob/main/LICENSE)
- [README](https://github.com/sindresorhus/pure/blob/main/README.md)
- [Releases](https://github.com/sindresorhus/pure/releases)
- [sindresorhus/pure on GitHub](https://github.com/sindresorhus/pure)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sindresorhus-pure