Powerlevel10k User Guide

Powerlevel10k is a theme for Zsh. It draws the command-line prompt you see every time you open a terminal, and it does so with three goals in mind: speed, flexibility, and a great out-of-the-box experience. It shows you contextual information — the current directory, Git status, the active Python or Node version, exit codes, background jobs, and dozens of other things — without ever making your prompt feel sluggish.

This guide walks you through installing Powerlevel10k, running its configuration wizard, customizing your prompt, and solving the problems people most commonly hit. Everything here is drawn directly from the project source, so the commands, parameters, and symbols described are exactly the ones the theme actually uses.

Note

Powerlevel10k changes only your prompt. It sets the PS1 and RPS1 shell parameters and prompt-related options, and it installs a single command, p10k. It does not touch your aliases, key bindings, ls colors, tab completion, or the behavior of git.

Important

The upstream project is in maintenance mode: no new features are planned, most bugs will go unfixed, and help requests are generally not answered. Powerlevel10k remains fully functional and is committed to backward compatibility indefinitely — but don't expect new releases.

Table of Contents

1. Quick Start
2. Requirements
3. Installation
4. Fonts
5. The Configuration Wizard
6. The p10k Command
7. Everyday Usage
8. Prompt Segments
9. Reading Git Status
10. Signature Features
11. Common Customizations
12. Writing Your Own Segment
13. Updating and Uninstalling
14. Troubleshooting
15. FAQ
16. How It Works
17. Quick Reference

1. Quick Start

Four steps get you from nothing to a configured prompt.

1. Install the recommended font (optional but highly recommended — see Fonts).
2. Install Powerlevel10k itself (see Installation).
3. Restart Zsh so the theme loads:

   exec zsh
   

4. Run the configuration wizard if it doesn't start on its own:

   p10k configure
   

The fastest possible manual install:

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ~/powerlevel10k
echo 'source ~/powerlevel10k/powerlevel10k.zsh-theme' >>~/.zshrc
exec zsh

[gitstatus] fetching gitstatusd ..  [ok]

On the first run, the wizard asks you a few questions about your terminal and your preferences, then writes a configuration file to ~/.p10k.zsh. That file is heavily commented, so it doubles as your customization reference.

Tip

Install the recommended font before running p10k configure. The wizard probes your terminal's font capabilities and hides prompt styles whose glyphs won't render — so a good font unlocks all the styles.

2. Requirements

Note

Powerlevel10k does not require custom fonts and works with default system fonts, but the full choice of style options is only available when using a Nerd Font.

3. Installation

Powerlevel10k works with a plain manual install or with every popular Zsh framework and plugin manager. If you are uncertain, choose the manual method — it works even alongside a plugin manager, as long as you disable any other active theme.

Manual

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ~/powerlevel10k
echo 'source ~/powerlevel10k/powerlevel10k.zsh-theme' >>~/.zshrc

Tip

Users in China can clone from the official gitee.com mirror for faster downloads: git clone --depth=1 https://gitee.com/romkatv/powerlevel10k.git ~/powerlevel10k.

Oh My Zsh

1. Clone into the custom themes directory:

   git clone --depth=1 https://github.com/romkatv/powerlevel10k.git "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k"
   

2. Open ~/.zshrc, find the line that sets ZSH_THEME, and change it to:

   ZSH_THEME="powerlevel10k/powerlevel10k"
   

Other frameworks and plugin managers

Prezto

Add to ~/.zpreztorc:

zstyle :prezto:module:prompt theme powerlevel10k

Zim

Add zmodule romkatv/powerlevel10k --use degit to ~/.zimrc, then run zimfw install.

Antidote

Add romkatv/powerlevel10k to ~/.zsh_plugins.txt.

Antigen

Add to ~/.zshrc (ensure antigen apply runs after it):

antigen theme romkatv/powerlevel10k

Zinit

Add to ~/.zshrc:

zinit ice depth=1; zinit light romkatv/powerlevel10k

The full matrix of supported managers and the exact line to add:

Note

For Zinit, Zplugin, and Zi the depth=1 ice is optional. Other ice types are neither recommended nor officially supported.

System packages

Homebrew (macOS/Linux)

brew install powerlevel10k
echo "source $(brew --prefix)/share/powerlevel10k/powerlevel10k.zsh-theme" >>~/.zshrc

Arch Linux

yay -S --noconfirm zsh-theme-powerlevel10k-git
echo 'source /usr/share/zsh-theme-powerlevel10k/powerlevel10k.zsh-theme' >>~/.zshrc

Alpine Linux

apk add zsh zsh-theme-powerlevel10k
mkdir -p ~/.local/share/zsh/plugins
ln -s /usr/share/zsh/plugins/powerlevel10k ~/.local/share/zsh/plugins/

After installing by any method, restart Zsh with exec zsh and run p10k configure if the wizard doesn't start automatically.

Warning

If you install via a plugin manager, make sure no other theme is active. A second theme will fight with Powerlevel10k for control of the prompt. See Troubleshooting → plugin manager.

Installing on a machine without Internet access

Powerlevel10k downloads a small compiled Git backend (gitstatusd) on first use. On an air-gapped machine you must pre-stage that binary.

1. On the offline machine, find its platform:

   uname -sm | tr '[A-Z]' '[a-z]'
   

   linux x86_64
   

2. On an Internet-connected machine, fetch the matching binary into the clone:

   target_uname="linux x86_64"   # replace with output from step 1
   git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ~/powerlevel10k
   GITSTATUS_CACHE_DIR="$HOME"/powerlevel10k/gitstatus/usrbin ~/powerlevel10k/gitstatus/install -f -s "${target_uname% *}" -m "${target_uname#* }"
   

3. Copy ~/powerlevel10k to the offline machine.
4. Add the source line to ~/.zshrc on the offline machine:

   echo 'source ~/powerlevel10k/powerlevel10k.zsh-theme' >>~/.zshrc
   

5. If ~/.zshrc sets ZSH_THEME, remove that line:

   sed -i.bak '/^ZSH_THEME=/d' ~/.zshrc
   

4. Fonts

Powerlevel10k looks best with a font that contains all the icons and powerline symbols it can draw. The project ships and recommends one:

👇 MesloLGS NF — Meslo Nerd Font, patched for Powerlevel10k. Contains every glyph the theme may need and is battle-tested across terminals and operating systems. 👇

Automatic installation

If you use iTerm2 or Termux, the wizard can install the font for you — just answer Yes when p10k configure asks whether to install Meslo Nerd Font.

Manual installation

1. Download these four files:
   • MesloLGS NF Regular.ttf
   • MesloLGS NF Bold.ttf
   • MesloLGS NF Italic.ttf
   • MesloLGS NF Bold Italic.ttf
2. Install each file (double-click → Install, or use your OS font manager).
3. Set your terminal to use the MesloLGS NF font family.
4. Run p10k configure to generate a fresh config that matches the new font.

A few common terminals (the project documents many more):

Config-file terminals:

Alacritty (alacritty.toml)

[font.normal]
family = "MesloLGS NF"

kitty (kitty.conf)

font_family MesloLGS NF

WezTerm (wezterm.lua)

local wezterm = require 'wezterm';
return {
    font = wezterm.font("MesloLGS NF"),
}

foot (foot.ini)

font=MesloLGS NF:size=12

Caution

Software installed via Snap cannot use system fonts. If you installed VS Code via Snap, remove it (sudo snap remove code) and install the official .deb build to use MesloLGS NF.

5. The Configuration Wizard

The wizard is the primary way to configure your prompt. Run it any time:

p10k configure

It asks a short series of questions — does this glyph render? do you prefer icons on the left or right? one line or two? — and from your answers it writes ~/.p10k.zsh. You can re-run it as often as you like to try a different look; it overwrites the config file each time.

Prompt styles

All styles except Pure are functionally equivalent: they show the same information and differ only in presentation.

Tip

If you use Vi keymap, pick a style that includes prompt_char (shown as a green ❯ in the wizard). It changes shape with the mode — ❯ insert, ❮ command, V visual, ▶ replace — and turns red when a command fails. Lean always has it; Rainbow and Classic have it only in the two-line, no-left-frame layout.

Wizard-driven options

The wizard also lets you choose, among other things:

• Charset — Unicode (pretty) or ASCII (renders everywhere). Available for all styles except Pure.
• Prompt height — one line or two. Two-line pairs beautifully with transient prompt.
• Prompt spacing — compact or sparse (empty line before each prompt).
• Icon density — few icons (informative only) or many icons (decorative too).
• Instant prompt mode — see Signature Features.
• Transient prompt — see Signature Features.

Note

The wizard hides any style whose glyphs your terminal can't render. If styles are missing, that's usually a font, locale, or color-depth issue — see Troubleshooting → missing styles.

6. The p10k Command

Installing the theme adds exactly one command to your shell: p10k. Run it with no arguments (or p10k help) to see usage.

p10k help

Usage: p10k command [options]

Commands:

  configure  run interactive configuration wizard
  reload     reload configuration
  segment    print a user-defined prompt segment
  display    show, hide or toggle prompt parts
  help       print this help message

Tip

Get detailed help for any subcommand, including worked examples, with p10k help segment or p10k help display.

p10k display — show, hide, or toggle prompt parts

p10k display takes one or more part-pattern=state-list arguments. The pattern selects prompt parts; the state list rotates through states on each call.

Selectable parts include:

States are show, hide, and print. A comma-separated state list rotates: the first call applies the first state, the next call the second, and so on.

Example — bind Ctrl+P to toggle the right prompt:

function toggle-right-prompt() { p10k display '*/right'=hide,show; }
zle -N toggle-right-prompt
bindkey '^P' toggle-right-prompt

7. Everyday Usage

Editing your prompt

Almost all customization happens in ~/.p10k.zsh. It's a Zsh script full of POWERLEVEL9K_* parameters with extensive inline comments. The two most important parameters live near the top:

typeset -g POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=(dir vcs prompt_char)
typeset -g POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=(status command_execution_time time)

These arrays decide which segments appear and in what order. Add a segment by listing its name; remove one by deleting it from the array.

Applying your changes

After editing ~/.p10k.zsh, apply it to the current shell:

source ~/.p10k.zsh

If instead you changed POWERLEVEL9K_* parameters directly in an interactive shell (not in the file), run:

p10k reload

Warning

Do not run source ~/.zshrc to apply changes. It can cause random errors and progressive Zsh slowdown. To fully reload your shell, type exit and open a new one, or use exec zsh. See Troubleshooting.

Note

By default, edits made by setting POWERLEVEL9K_* directly in a running shell need a p10k reload to take effect. Setting POWERLEVEL9K_DISABLE_HOT_RELOAD=false removes that need at the cost of a marginally slower prompt.

8. Prompt Segments

A segment is one unit of information in the prompt — the directory, Git status, the clock, and so on. Powerlevel10k ships dozens. Enable a segment by adding its name to POWERLEVEL9K_LEFT_PROMPT_ELEMENTS or POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS. Enabling extra segments does not slow down your prompt or Zsh startup.

Core segments

Language and version-manager segments

Cloud, infra, and tooling segments

Tip

This is the full set of built-in segment categories, but not every segment is enabled by default. Open ~/.p10k.zsh, search for the segment you want, and uncomment it (or add its name to a prompt-elements array).

9. Reading Git Status

When you're inside a Git repository and using the Lean, Classic, or Rainbow style, the vcs segment can look like this:

feature:master wip ⇣42⇡42 ⇠42⇢42 *42 merge ~42 +42 !42 ?42

Each piece has a precise meaning, computed by the bundled Git backend:

Note

The ? for untracked files is a normal question mark, not a missing glyph. If you'd rather not see untracked files, search for untracked files in ~/.p10k.zsh.

To change the format of Git status, open ~/.p10k.zsh, search for my_git_formatter, and edit that function's source — it builds the string you see above.

Tip

If Git status appears grey and then gets colored a moment later, that's expected. Grey means Powerlevel10k is computing fresh status in the background; the prompt refreshes automatically (in color) when it finishes. The grace period before going async is POWERLEVEL9K_VCS_MAX_SYNC_LATENCY_SECONDS.

Note

By default Powerlevel10k's vcs segment ignores the Git repository at $HOME/.git (controlled by POWERLEVEL9K_VCS_DISABLED_WORKDIR_PATTERN='~'). Remove that parameter to show status for your home-directory repo.

10. Signature Features

Uncompromising performance

When you press ENTER, the next prompt appears instantly — no lag, regardless of how many segments you enable or how large the Git repository is. Other prompts capable of showing the same information either lag or show stale data and refresh later; Powerlevel10k gives you a fast prompt and up-to-date information.

Instant prompt

If your ~/.zshrc loads slow plugins (such as nvm or pyenv), Zsh can take a while to start. Instant prompt prints your prompt immediately on startup so you can begin typing while plugins finish loading in the background — it can remove startup lag even when the theme isn't what's causing it.

Enable it through p10k configure, or manually by adding this block near the top of ~/.zshrc:

# Enable Powerlevel10k instant prompt. Should stay close to the top of ~/.zshrc.
# Initialization code that may require console input (password prompts, [y/n]
# confirmations, etc.) must go above this block; everything else may go below.
if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
  source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
fi

Important

Copy the lines verbatim. While instant prompt is active, standard input is redirected to /dev/null and output is buffered to a temporary file. Any startup code that needs to read from the console (a keyring password, a [y/n] prompt) must be placed above the instant-prompt block, or it will break.

Tune the warning behavior with POWERLEVEL9K_INSTANT_PROMPT:

Note

Instant prompt requires Zsh ≥ 5.4. It's safe to enable on older Zsh — it simply does nothing.

Transient prompt

When enabled (via p10k configure), transient prompt trims every past prompt down to a minimal form once you accept a command line. This makes it much easier to copy a series of commands out of your scrollback.

Tip

Transient prompt pairs especially well with a two-line prompt: you get the extra typing space of two lines without the usual scrollback-density penalty.

Show on command

Some segments are only relevant to certain commands. Show on command makes a segment appear only while you're typing a command that uses it. For example, show the Kubernetes context only when typing kubectl, helm, or kubens:

typeset -g POWERLEVEL9K_KUBECONTEXT_SHOW_ON_COMMAND='kubectl|helm|kubens'

To make such a segment always visible, remove its SHOW_ON_COMMAND parameter. To make it always hidden until needed, keep it. You can also script a toggle (see the kube-toggle recipe in Common Customizations).

Current directory that just works

The dir segment highlights the important parts of your path and, when space is tight, truncates the least useful parts first — shortening each leading segment to its shortest unique prefix. Important segments (the first, the last, Git repository roots) are kept bright and never truncated.

Tip

Copy a truncated directory from your prompt and press TAB — it completes back to the full original path.

Powerlevel9k and Pure compatibility

Powerlevel10k understands every POWERLEVEL9K_* parameter from Powerlevel9k, so migrating is as simple as pointing your config at the new theme — your prompt looks the same but runs much faster. It can also exactly replicate the Pure theme (choose Pure in the wizard) while still letting you use Powerlevel10k features like instant and transient prompt.

11. Common Customizations

Add username and hostname to the prompt

By default context (user@hostname) appears only when you're root or on SSH. To always show it, open ~/.p10k.zsh, find the context section, and remove this line:

# Don't show context unless running with privileges or in SSH.
# Tip: Remove the next line to always show context.
typeset -g POWERLEVEL9K_CONTEXT_{DEFAULT,SUDO}_{CONTENT,VISUAL_IDENTIFIER}_EXPANSION=

You can also move context between POWERLEVEL9K_LEFT_PROMPT_ELEMENTS and POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS.

Change a segment's color

Colors are numbers from 0–255 (colors 0–15 vary by terminal palette; 16–255 are fixed). Truecolor terminals also accept #RRGGBB.

typeset -g POWERLEVEL9K_TIME_FOREGROUND=160        # bright red, numbered color
typeset -g POWERLEVEL9K_TIME_FOREGROUND='#FF0000'  # bright red, truecolor

Apply with source ~/.p10k.zsh. To preview all 256 numbered colors in your terminal:

for i in {0..255}; do print -Pn "%K{$i}  %k%F{$i}${(l:3::0:)i}%f " ${${(M)$((i%6)):#3}:+$'\n'}; done

Tip

To make low-numbered colors track your terminal's color scheme, use Rainbow, Lean → 8 colors, or Pure → Original. Other styles use fixed high-numbered colors and look the same in every palette.

Toggle a segment with a keypress

This kube-toggle function flips the kubecontext segment between always shown and show on command, then refreshes the prompt:

function kube-toggle() {
  if (( ${+POWERLEVEL9K_KUBECONTEXT_SHOW_ON_COMMAND} )); then
    unset POWERLEVEL9K_KUBECONTEXT_SHOW_ON_COMMAND
  else
    POWERLEVEL9K_KUBECONTEXT_SHOW_ON_COMMAND='kubectl|helm|kubens'
  fi
  p10k reload
  if zle; then
    zle push-input
    zle accept-line
  fi
}
zle -N kube-toggle
bindkey '^]' kube-toggle  # ctrl-] to toggle kubecontext

Make it look like the robbyrussell Oh My Zsh theme

Use the bundled config: download config/p10k-robbyrussell.zsh, save it as ~/.p10k.zsh, and source ~/.p10k.zsh from ~/.zshrc.

12. Writing Your Own Segment

If no built-in segment does what you need, you can define one with the same speed and flexibility as the built-ins. A custom segment is a Zsh function named prompt_<name> that calls p10k segment to emit its content.

Example — a core segment that reports whether a file named core exists in the current directory, with its size and a deletability state:

zmodload -F zsh/stat b:zstat

function prompt_core() {
  local size=()
  if ! zstat -A size +size core 2>/dev/null; then
    # No 'core' file in the current directory.
    return
  fi
  if [[ -w . ]]; then
    local state=DELETABLE
  else
    local state=PROTECTED
  fi
  p10k segment -s $state -i '⭐' -f blue -t ${size[1]}b
}

Enable it by adding core to POWERLEVEL9K_LEFT_PROMPT_ELEMENTS or POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS. Then style it like any built-in segment:

POWERLEVEL9K_CORE_FOREGROUND=red                          # default foreground
POWERLEVEL9K_CORE_DELETABLE_BACKGROUND=green              # background when DELETABLE
POWERLEVEL9K_CORE_PROTECTED_VISUAL_IDENTIFIER_EXPANSION='❎'  # icon when PROTECTED
POWERLEVEL9K_CORE_PROTECTED_CONTENT_EXPANSION=''          # hide size when PROTECTED

p10k segment accepts these options:

Tip

Prefix your own segment names with my_ (e.g. my_weather) to avoid clashing with future built-in segments.

Note

p10k segment can only be called while the prompt is rendering — i.e. from inside a prompt_<name> function. Calling it elsewhere is an error.

Lifecycle hooks

You can also define optional functions that Powerlevel10k calls at specific points: p10k-on-init, p10k-on-pre-prompt, p10k-on-post-prompt, and p10k-on-post-widget. These let advanced configs run code as the prompt initializes and around each render.

13. Updating and Uninstalling

Updating

The update command depends on how you installed. Always restart Zsh after updating (exec zsh) — do not source ~/.zshrc.

Uninstalling

1. Remove the instant-prompt block (top of ~/.zshrc) and the config-sourcing line ([[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh, near the bottom).
2. Remove every reference to powerlevel10k from ~/.zshrc, ~/.zpreztorc, and ~/.zimrc.
3. Verify nothing remains:

   grep -E 'p10k|powerlevel10k' ~/.zshrc ~/.zpreztorc ~/.zimrc 2>/dev/null
   

4. Delete your config file:

   rm -f ~/.p10k.zsh
   

5. Delete the source files (manual install shown; use the uninstall command for your manager otherwise):

   rm -rf ~/powerlevel10k
   

6. Restart Zsh (exec zsh).
7. Delete cache files:

   rm -rf -- "${XDG_CACHE_HOME:-$HOME/.cache}"/p10k-*(N) "${XDG_CACHE_HOME:-$HOME/.cache}"/gitstatus
   

14. Troubleshooting

Error: [oh-my-zsh] theme 'powerlevel10k/powerlevel10k' not found

Cause: Oh My Zsh can't find the theme directory, or the theme is being loaded twice.

Solution: First check whether the theme actually loaded:

typeset -p P9K_VERSION

• If it prints a version (e.g. typeset P9K_VERSION=1.19.14), the theme is already loaded by another mechanism — remove ZSH_THEME="powerlevel10k/powerlevel10k" from ~/.zshrc.
• If it errors with no such variable: P9K_VERSION, the directory is missing — clone it:

  git clone --depth=1 https://github.com/romkatv/powerlevel10k.git "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k"
  

Then exec zsh.

Question mark in prompt

Cause: A plain ? means you have untracked files (?2 = 2 untracked). A weird question mark means a missing font glyph.

Solution: For the plain ?, that's normal — run git status to see the files, or search for untracked files in ~/.p10k.zsh to change the symbol. For a broken-looking glyph, see the next entry.

Icons, glyphs, or powerline symbols don't render

Cause: Your terminal isn't using a font that contains the required glyphs.

Solution: Restart your terminal, install the recommended font, and run p10k configure.

Error: character not in range

Cause: Your locale doesn't support UTF-8.

Solution: Test with echo '❯'. If it errors, fix your locale — set a UTF-8 locale for your OS. Over SSH, ensure your client forwards a UTF-8 locale.

Cursor is in the wrong place / prompt wraps weirdly

Cause: Usually a locale issue, a font issue, or a terminal that mis-measures glyph width.

Solution:

1. Run echo '❯'; if it errors, fix your locale (above).
2. If ❯ prints but the cursor is misplaced, install the recommended font and run p10k configure.
3. If it still happens, add unset ZLE_RPROMPT_INDENT to the bottom of ~/.zshrc.

Prevention: Use a true monospace font and a UTF-8 locale. Konsole, Hyper, and the VS Code terminal can mis-render "wide" Unicode glyphs — use a different terminal or remove wide glyphs from your prompt.

Configuration wizard runs automatically every time Zsh starts

Cause: Your ~/.zshrc aborts (usually a syntax error) before reaching the line that sources ~/.p10k.zsh, so Powerlevel10k sees no config and re-runs the wizard.

Solution: Start Zsh without the wizard to see the hidden errors, then fix ~/.zshrc:

POWERLEVEL9K_DISABLE_CONFIGURATION_WIZARD=true zsh

Some prompt styles are missing from the configuration wizard

Cause: Your terminal lacks a capability that those styles need.

Solution: Check each capability:

• Truecolor (for Pure + Snazzy): need Zsh ≥ 5.7.1 and COLORTERM=24bit/truecolor. Verify: print -P '%F{#ff0000}red%f'.
• 256 colors (for all but Lean 8-color): verify print $terminfo[colors].
• UTF-8 locale (for Unicode styles): verify locale -a.
• MULTIBYTE option enabled: verify print -r -- ${options[MULTIBYTE]}.
• Font glyphs: restart terminal, install the recommended font, re-run the wizard.

Extra or missing spaces compared to Powerlevel9k

Cause: Powerlevel10k respects ZLE_RPROMPT_INDENT and uses consistent icon spacing, both of which differ from Powerlevel9k.

Solution: For Powerlevel9k-identical spacing, add to ~/.zshrc:

ZLE_RPROMPT_INDENT=0                        # removes trailing space on the right prompt
POWERLEVEL9K_LEGACY_ICON_SPACING=true       # Powerlevel9k icon spacing

Caution

Don't set POWERLEVEL9K_LEGACY_ICON_SPACING when using a config generated by p10k configure. Some Zsh versions also have bugs triggered by ZLE_RPROMPT_INDENT=0; remove it if you see visual artifacts.

Weird things happen after typing source ~/.zshrc

Cause: Re-sourcing ~/.zshrc is unsafe — it can produce random errors and progressively slow down Zsh, whether or not you use Powerlevel10k.

Solution: Don't source ~/.zshrc. To apply changes, restart the shell: type exit and open a new one, or run exec zsh. (This also explains transient prompt "stopping" after a source ~/.zshrc.)

Horrific mess when resizing the terminal window

Cause: When a terminal reflows text on resize, the vertical distance between the prompt start and the cursor can change, and Zsh redraws the prompt in the wrong place. This affects all themes, not just Powerlevel10k.

Solution (mitigations):

• Use kitty ≥ 0.24.0 and set POWERLEVEL9K_TERM_SHELL_INTEGRATION=true.
• Disable text reflow on resize in your terminal settings (or use a terminal that doesn't reflow).
• Reduce long lines between prompt start and cursor:

  POWERLEVEL9K_SHOW_RULER=false
  POWERLEVEL9K_MULTILINE_FIRST_PROMPT_GAP_CHAR=' '
  POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=()
  

Icons cut off in Konsole

Cause: Konsole cuts off glyphs wider than one column when using a non-monospace font.

Solution: Use a monospace font or a different terminal. As a targeted workaround, add a trailing space to the affected icon, e.g.:

typeset -g POWERLEVEL9K_OS_ICON_CONTENT_EXPANSION='${P9K_CONTENT} '  # extra space

Incorrect Git status in prompt

Cause: The Git backend uses libgit2, which has gaps — notably it does not support skipHash (which may be enabled implicitly by Git's manyFiles feature).

Solution: Run git config -l and check for skipHash. If it's enabled, consider disabling it. Also see the grey-then-colored note — a brief grey status is normal, not a bug.

15. FAQ

Q: Which parts of my shell does Powerlevel10k change? Only the prompt. It sets prompt-related Zsh options and the PS1/RPS1 parameters, and adds the p10k command. It does not affect ls colors, git behavior, tab completion, key bindings, aliases, the terminal title, or any other prompt parameters.

Q: Is it really fast? Yes — measurably. The project points to zsh-bench for benchmarks. No configuration makes Powerlevel10k slow; if you ever see prompt lag, that's considered a bug worth reporting.

Q: Is Powerlevel10k fast to load (not just to render)? Yes, and with instant prompt enabled it can make your shell feel instant even when other plugins are slow to load.

Q: What's the minimum Zsh version? Zsh 5.3 or newer works. Fast startup (instant prompt) needs ≥ 5.4; the wizard's Pure + Snazzy scheme needs ≥ 5.7.1.

Q: Why does Powerlevel10k spawn extra processes? The vcs segment uses gitstatus as its backend, which runs gitstatusd and a helper zsh. Powerlevel10k may also spawn a zsh to do work off the prompt's critical path. These background processes aren't shared between shells and terminate when the parent zsh exits.

Q: Why do some segments appear and disappear as I type? That's the show on command feature — a segment configured to show only when the command you're typing uses the relevant tool. Search for SHOW_ON_COMMAND in ~/.p10k.zsh to change it.

Q: I'm using Powerlevel9k with Oh My Zsh — how do I migrate? Clone Powerlevel10k into the custom themes dir, then point ZSH_THEME at it:

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k"
sed -i.bak 's/powerlevel9k/powerlevel10k/g' ~/.zshrc
exec zsh

Your existing POWERLEVEL9K_* parameters keep working.

Q: Will my prompt look exactly the same as it did in Powerlevel9k? Almost. Differences: only the git VCS backend is enabled by default (add svn/hg to POWERLEVEL9K_VCS_BACKENDS if needed, but they're slow); POWERLEVEL9K_VCS_SHOW_SUBMODULE_DIRTY=true isn't supported; and some Powerlevel9k bugs (inconsistent spacing, ignored options) were fixed. See the spacing troubleshooting for exact-match flags.

Q: What's the relationship between Powerlevel9k and Powerlevel10k? Powerlevel10k was forked from Powerlevel9k in March 2019 to iterate faster on performance and features. They're independent projects with no shared committers; virtually all Powerlevel10k code has since been rewritten. Use one or the other, not both.

Q: Can a completed command's prompt show that command's exit code? No. When you press ENTER, the command's exit status isn't known yet, and once it finishes the prompt for it can no longer be redrawn. So each command's error status shows up in the next prompt.

Q: What's the best prompt style in the wizard? It's personal preference, but: prefer Lean over Pure unless you're migrating from Pure; use Rainbow, Lean → 8 colors, or Pure → Original if you want colors to follow your terminal palette; enable transient prompt and use a two-line prompt for the best copy-paste experience.

Q: How do I export GPG_TTY when using instant prompt? Anywhere in ~/.zshrc, use export GPG_TTY=$TTY — it's faster than $(tty) and works with or without instant prompt.

Q: How do I initialize direnv with instant prompt? Put the direnv export line above the instant-prompt block and the direnv hook line below it:

(( ${+commands[direnv]} )) && emulate zsh -c "$(direnv export zsh)"
# ... instant prompt block ...
(( ${+commands[direnv]} )) && emulate zsh -c "$(direnv hook zsh)"

Q: Where do I get help or report bugs? Open an issue (best), or use Gitter. Note the project's limited-support status described at the top of this guide.

16. How It Works

You don't need this section to use Powerlevel10k, but it explains why the prompt is both fast and accurate. (Full architecture and internals are in the Admin Guide.)

Powerlevel10k has two cooperating layers:

• A Zsh frontend — the theme itself (powerlevel10k.zsh-theme plus the engine in internal/p10k.zsh). It defines your prompt, draws segments, and manages the configuration wizard.
• A compiled Git backend — gitstatusd, from the bundled gitstatus project. It computes Git status far faster than git status by talking to libgit2 directly, running as a background daemon that the theme queries.

The key to the "fast and up to date" behavior is that Git status is computed asynchronously. After each command, Powerlevel10k asks gitstatusd for status. If the answer comes back within a few milliseconds, it's shown immediately; if not, the last known status is shown in grey and the prompt is refreshed in color the moment the fresh status arrives. Large repositories never block your prompt.

The first time the vcs segment runs, Powerlevel10k downloads (or uses a vendored copy of) the gitstatusd binary for your platform — which is the [gitstatus] fetching gitstatusd .. message you may see on first launch.

17. Quick Reference

Essential commands

Key files

Key parameters

Git status symbols

⇣ behind remote · ⇡ ahead of remote · ⇠ behind push remote · ⇢ ahead of push remote · * stashes · ~ conflicts · + staged · ! unstaged · ? untracked · #tag / @commit when not on a branch · ─ count unknown (large repo)