# Spaceship Prompt: a Zsh prompt built from toggleable sections

> Spaceship is a Zsh prompt that renders Git status, language runtimes, Docker and Kubernetes context from a set of independently configurable sections. It is a good fit if you already live in Zsh and want per-section control; it is not a shell-agnostic prompt.

**spaceship-prompt/spaceship-prompt** — 🚀✨ Minimalistic, powerful and extremely customizable Zsh prompt

- Repository: https://github.com/spaceship-prompt/spaceship-prompt
- Website: https://spaceship-prompt.sh
- Stars: 20,577 · Forks: 970
- Language: Shell
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/spaceship-prompt-spaceship-prompt

## What Spaceship solves, and who it is written for

A default Zsh prompt tells you almost nothing. Spaceship's premise is that the prompt line is the cheapest place to surface context you would otherwise fetch with a command: the current Git or Mercurial branch state, which language runtime is active, the Docker version, the Kubernetes context, the package version in the current directory, battery level, and a marker for background jobs. The README lists all of these as built-in features.

The audience is narrow on purpose. Spaceship requires Zsh v5.2 or newer, and the README tells you to verify that with echo $ZSH_VERSION. It also requires a Powerline Font or a Nerd Font installed and selected in the terminal, with Fira Code named as a popular choice. If your terminal still uses a plain monospace font, the prompt's separator glyphs will not render, and the README provides a check for that: echoing a specific byte sequence should print a branch symbol.

That combination (Zsh plus a patched font) is the entry ticket. Someone who wants a prompt for Bash, Fish or a POSIX sh will not find one here. Someone who wants a prompt that degrades gracefully on a stock font will also be disappointed, because the visual structure depends on those glyphs.

## Sections, async.zsh and the prompt_spaceship_setup entry point

The repository layout explains the design better than the marketing copy does. There is a sections/ directory, a lib/ directory, an async.zsh file, a spaceship.zsh entry script, a spaceship.zsh-theme wrapper for Oh My Zsh, and a prompt_spaceship_setup file. Each entry under sections/ corresponds to one piece of information the prompt can display. The prompt is therefore not a single formatting string you edit; it is a collection of small modules that each decide whether they apply to the current directory and, if so, what to print.

The async.zsh file is the performance-relevant part. Prompt sections that shell out (Git status, runtime versions) are the expensive ones, and the presence of an asynchronous helper in the tree indicates that Spaceship is designed to avoid blocking the prompt on every command. The README's FAQ links to a note about why the prompt may not look like the preview, which is a hint that what renders depends on the ambient state of the machine rather than on a fixed template.

Configuration is expressed through environment variables, conventionally prefixed SPACESHIP_. The related searches around spaceship_prompt_order and prompt configuration point at the same mechanism: ordering and enabling sections is done through variables set in .zshrc before the prompt is sourced. The README does not reproduce the full variable list; it points to spaceship-prompt.sh/config/intro for that, so the website is the authoritative reference rather than the repository README.

## Installing Spaceship with Homebrew, npm or Oh My Zsh

The README offers a long list of installation methods: Homebrew, Oh My Zsh, npm, prezto, zim, antigen, antibody, zinit and zgen. Pick the one that matches the plugin manager you already use. The Homebrew path is two commands. The first installs the package, and the second appends a source line to your .zshrc using the Homebrew prefix.

```bash
brew install spaceship
echo "source $(brew --prefix)/opt/spaceship/spaceship.zsh" >>! ~/.zshrc
```

After that, open a new shell. You should see the two-line Spaceship prompt instead of your previous one. If the separators appear as boxes or question marks, the font requirement from the previous section is the thing to fix first.

The npm route installs globally and, per the README, the postinstall script asks whether to source Spaceship in ~/.zshrc. The package.json confirms this: the postinstall key runs ./scripts/install, and there is a matching postuninstall script. If your package manager runs lifecycle scripts in a restricted mode, that prompt will not appear and you will need to add the source line yourself.

```bash
npm install -g spaceship-prompt
```

For Oh My Zsh users, the theme is installed by cloning into the custom themes directory, symlinking spaceship.zsh-theme, and setting ZSH_THEME="spaceship".

```bash
git clone https://github.com/spaceship-prompt/spaceship-prompt.git "$ZSH_CUSTOM/themes/spaceship-prompt" --depth=1
ln -s "$ZSH_CUSTOM/themes/spaceship-prompt/spaceship.zsh-theme" "$ZSH_CUSTOM/themes/spaceship.zsh-theme"
```

A first real use is to turn a section off and confirm the change. Set the relevant SPACESHIP_ variable in .zshrc before the source line, then restart the shell. Because the configuration surface is variable-based rather than file-based, the fastest way to learn what is available is the configuration page the README links to, not the repository itself.

## Where Spaceship gets in the way

The font dependency is a real cost, not a footnote. Spaceship requires a Powerline or Nerd Font, and that requirement follows you onto every machine you SSH into if you expect the prompt to look right there. On a jump host where you cannot install fonts locally, the glyphs in the prompt are the terminal's problem, not Spaceship's.

The second limitation is the documentation split. The README is a feature list and an installation menu; it does not enumerate the SPACESHIP_ variables, and it does not document a rollback procedure for the npm postinstall script. The configuration reference lives on spaceship-prompt.sh. That is a normal arrangement for a project with its own site, but it means a reader who only opens the repository will not find the settings they need to change behavior.

The third is the async machinery. The presence of async.zsh signals that the prompt is doing work in the background, and background work introduces ordering questions: a section can render after the prompt has already been drawn, or not at all if the shell exits first. The README's own FAQ entry about the prompt not matching the preview is consistent with this. If you need a prompt whose output is deterministic and identical on every draw, a synchronous prompt with fewer sections is easier to reason about.

## Spaceship against Starship, and against doing nothing

The most common comparison is with Starship, and the difference is architectural rather than cosmetic. Starship is a cross-shell prompt: it works in Bash, Zsh, Fish and others, and it is configured through a single TOML file. Spaceship is Zsh-only and is configured through environment variables in .zshrc, with a sections/ directory of shell files behind it. If your team uses more than one shell, Starship gives you one configuration to maintain; Spaceship gives you a Zsh-native implementation that follows Zsh's own plugin conventions.

The second alternative is the prompt you already have. Oh My Zsh ships themes, and a hand-written prompt in .zshrc costs nothing to install and has no font requirement beyond what you already use. Spaceship earns its place when you want the specific set of indicators it ships (Git and Mercurial status, runtime versions, Docker and Kubernetes context, package versions, battery, background job marker) without writing the shell logic for each one. If you only want a Git branch in your prompt, the section machinery is more than you need.

A third option worth naming is a prompt built from a generator, which the related searches suggest people look for. Spaceship is not that. It is a fixed set of sections with variable-based configuration, not a tool that emits a prompt from a visual editor.

## Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-02, which is recent relative to the release history. The most recent release listed is v4.22.5 on 2026-07-01, preceded by v4.22.4 on 2026-06-24 and v4.22.3 on 2026-06-03. That cadence suggests patch releases arrive fairly often, so pinning to a version and reading CHANGELOG.md before upgrading is the practical approach.

The licence is MIT, declared both in the repository and in the license field of package.json. MIT is permissive: it allows use, modification and redistribution with the copyright notice and permission notice retained. That is a statement about the licence text, not legal advice; if you redistribute Spaceship inside a product, have your own counsel read the terms.

The upgrade cost depends on how you installed it. Homebrew and npm upgrades are package-manager operations, and the npm path reruns postinstall, which touches .zshrc. The Oh My Zsh path is a git clone with --depth=1, so updating means pulling in that directory and re-checking the symlink to spaceship.zsh-theme. The Makefile also exposes a zwc target that compiles the .zsh and .zsh-theme files into .zwc bytecode, plus a clean target that deletes those files; if you use compiled bytecode, remember to recompile after an upgrade, because stale .zwc files are a classic source of confusing behavior.

## Conclusion

Adopt Spaceship if you already run Zsh 5.2 or newer and want prompt content you can switch on and off section by section, with a Nerd Font in the terminal. Skip it if you use Bash or Fish, or if you want a prompt that works without a patched font. Before committing, check your Zsh version with echo $ZSH_VERSION, confirm your terminal renders the Powerline glyph, and read the configuration docs at spaceship-prompt.sh/config/intro so you know which SPACESHIP_ variables exist for the sections you plan to use.

## FAQ

### What are the differences between the Spaceship prompt and the Starship prompt?

Spaceship is a Zsh-only prompt configured through environment variables in .zshrc, with its logic split across a sections/ directory. Starship is a cross-shell prompt, so the practical difference is whether you need one prompt for several shells or a Zsh-native one.

### What is the Spaceship prompt in Zsh?

It is a Zsh prompt that displays context such as Git and Mercurial status, language runtime versions, Docker version, Kubernetes context, package versions, battery level and a marker for background jobs. It requires Zsh v5.2 or newer and a Powerline or Nerd Font.

### How do I configure the Spaceship prompt?

Configuration is done through SPACESHIP_ environment variables set in .zshrc before Spaceship is sourced, which is how sections are enabled, disabled and ordered. The README points to spaceship-prompt.sh/config/intro for the full reference rather than listing the variables itself.

### Do I need Oh My Zsh to use Spaceship?

No. The README documents installation through Homebrew, npm, prezto, zim, antigen, antibody, zinit and zgen as well as Oh My Zsh. The Oh My Zsh path is one option among many, using the spaceship.zsh-theme wrapper.

## Sources

- [License: MIT](https://github.com/spaceship-prompt/spaceship-prompt/blob/master/LICENSE)
- [Project website](https://spaceship-prompt.sh)
- [README](https://github.com/spaceship-prompt/spaceship-prompt/blob/master/README.md)
- [Releases](https://github.com/spaceship-prompt/spaceship-prompt/releases)
- [spaceship-prompt/spaceship-prompt on GitHub](https://github.com/spaceship-prompt/spaceship-prompt)

---

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