Guide · Open source
How to use spaceship-prompt: install and configure the Zsh prompt
Updated · written with AI from the project's own documentation and checked against our catalogue data
Spaceship is a minimalistic, customizable prompt for the Zsh shell. The prompt line is the text you see before each command, and Spaceship uses it to show things like Git repository status, language versions and Docker or Kubernetes context. This guide covers what you need before installing, how to install it with a few common methods, and where to go to customize it.
Spaceship Promptspaceship-prompt/spaceship-prompt · ★ 20.6k · MIT Install options & downloads Quick start
- 1Check your Zsh version. Run echo $ZSH_VERSION and confirm it reports 5.2 or newer.
- 2Install a Nerd Font or Powerline Font. Install the font and select it in your terminal settings so icons render correctly.
- 3Install Spaceship. Use brew install spaceship or npm install -g spaceship-prompt, or pick a plugin manager method from the README.
- 4Source Spaceship in .zshrc. Make sure your .zshrc loads Spaceship, either with the source line from the install step or through your plugin manager.
- 5Open a new shell. Start a new terminal session so the prompt loads, then move into a Git repository or language project to see the sections in action.
- 6Customize sections. Read the configuration docs at spaceship-prompt.sh to change individual sections to suit your needs.
What you need before installing Spaceship
Spaceship is built for the Zsh shell and requires Zsh v5.2 or newer. You can check your version by running the command shown below.
Spaceship also needs a Powerline Font or a Nerd Font installed and selected in your terminal. The README says this is required for icons to display correctly. Fira Code is mentioned as a popular choice, and Nerd Font is described as the better option.
- Zsh 5.2 or newer
- A Powerline Font or Nerd Font installed and set in your terminal
echo $ZSH_VERSIONInstall Spaceship with Homebrew or npm
Homebrew is the quickest route if you already use it. After installing, add the prompt initialization line to your .zshrc file so Spaceship loads each time you open a shell.
If you use Node.js, you can install Spaceship globally with npm. The README says this command also asks you to source Spaceship in your ~/.zshrc file.
- Homebrew: run the install command, then add the source line to ~/.zshrc
- npm: run the global install command and follow its prompt to source Spaceship in ~/.zshrc
brew install spaceship
npm install -g spaceship-promptInstall Spaceship with a Zsh plugin manager
If you already use a Zsh manager, you can add Spaceship through it instead. The README lists instructions for Oh-My-Zsh, prezto, zim, antigen, antibody, zinit, zgen, zplug and sheldon, among others. Each one uses a different line or file, so follow the section that matches your manager.
For Oh-My-Zsh, you clone the repo into the themes folder, symlink spaceship.zsh-theme, and set ZSH_THEME to spaceship in your .zshrc.
- Oh-My-Zsh: set ZSH_THEME="spaceship" in .zshrc after the clone and symlink steps
- zinit: add the light-load line where you add your other Zsh plugins
- zim: add a zmodule line to .zimrc, then run zimfw install
zinit light spaceship-prompt/spaceship-promptInstall manually from GitHub
If none of the package methods work for you, the README describes a manual install. Clone the repo to a folder such as $HOME/.zsh/spaceship, then source spaceship.zsh from your .zshrc.
Arch users can install the AUR package spaceship-prompt. The README also mentions an unmaintained git package, spaceship-prompt-git.
- Clone the repo to a location of your choice, for example $HOME/.zsh/spaceship
- Source spaceship.zsh in ~/.zshrc
mkdir -p "$HOME/.zsh"
git clone --depth=1 https://github.com/spaceship-prompt/spaceship-prompt.git "$HOME/.zsh/spaceship"
source "$HOME/.zsh/spaceship/spaceship.zsh"What Spaceship shows and how to customize it
Spaceship works well out of the box. The README lists sections for hostname and username, Git and Mercurial repository status, runtime versions for languages such as Node.js, Rust, Python, Ruby, Swift, Go and PHP, Docker version, Kubernetes context, package versions, and battery level. It also shows an indicator for background jobs.
Configuration is done section by section. The official docs at spaceship-prompt.sh cover the configuration options, and the advanced section explains how to create a custom section and use per-directory configuration.
- Configuration reference: https://spaceship-prompt.sh/config/intro
- Creating a custom section: https://spaceship-prompt.sh/advanced/creating-section
What people use it for
- Seeing the current Git branch and repository status in the prompt while working in a project
- Checking Node.js, Python, Rust or Go runtime versions in the folder you are working in
- Viewing Docker or Kubernetes context before running commands
- Keeping a battery level indicator visible in the prompt on a laptop
Frequently asked questions
Is Spaceship free to use?
Spaceship is released under the MIT licence, according to the project's repository details. The MIT licence generally allows free use, modification and redistribution, but check the licence file in the repo for the full terms.
Does Spaceship work with Bash or Fish?
No. Spaceship is a prompt for Zsh and the README says the project requires Zsh v5.2 or newer. If you use Bash or Fish, look at a prompt that supports your shell, such as Starship or Oh My Posh.
Why do my prompt icons show as boxes or question marks?
The README says a Powerline Font or Nerd Font must be installed and selected in your terminal for icons to display correctly. Install one of those fonts and set it in your terminal's preferences, then open a new session.
Do I need Homebrew or npm to install Spaceship?
No. The README lists several methods, including Homebrew, npm, a manual git clone, the AUR on Arch, and many Zsh plugin managers such as zinit, zim and Oh-My-Zsh. Choose whichever fits your setup.
How is Spaceship different from Powerlevel10k or Starship?
Spaceship is a Zsh-only prompt focused on simplicity by default with section-by-section configuration. The project lists Powerlevel10k, Starship, Pure and Oh My Posh as comparable projects, so compare them on the features and shell support you need.
Can I add my own information to the prompt?
Yes. The README points to an advanced guide on creating a custom section, which lets you show information of your choice in the prompt.
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
Spaceship suits Zsh users who want Git, language and environment details in their prompt with little setup, and who are happy to install a Nerd Font. If you use Bash or Fish, or want a prompt with no live background checks, pick a different tool such as Starship or Oh My Posh.
Install options & downloads