# 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](#1-quick-start)
2. [Requirements](#2-requirements)
3. [Installation](#3-installation)
4. [Fonts](#4-fonts)
5. [The Configuration Wizard](#5-the-configuration-wizard)
6. [The `p10k` Command](#6-the-p10k-command)
7. [Everyday Usage](#7-everyday-usage)
8. [Prompt Segments](#8-prompt-segments)
9. [Reading Git Status](#9-reading-git-status)
10. [Signature Features](#10-signature-features)
11. [Common Customizations](#11-common-customizations)
12. [Writing Your Own Segment](#12-writing-your-own-segment)
13. [Updating and Uninstalling](#13-updating-and-uninstalling)
14. [Troubleshooting](#14-troubleshooting)
15. [FAQ](#15-faq)
16. [How It Works](#16-how-it-works)
17. [Quick Reference](#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](#4-fonts)).
2. **Install Powerlevel10k** itself (see [Installation](#3-installation)).
3. **Restart Zsh** so the theme loads:
   ```zsh
   exec zsh
   ```
4. **Run the configuration wizard** if it doesn't start on its own:
   ```zsh
   p10k configure
   ```

The fastest possible manual install:

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

```text
[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

| Requirement | Detail |
|-------------|--------|
| **Zsh** | Version 5.3 or newer. Fast startup (instant prompt) requires Zsh ≥ 5.4. The configuration wizard's Pure + Snazzy color scheme needs Zsh ≥ 5.7.1. |
| **A UTF-8 locale** | Needed for Unicode prompt styles. Verify with `locale -a`. An ASCII fallback is available for every style except Pure. |
| **A 256-color (or truecolor) terminal** | All prompt styles except Lean → 8 colors need at least 256 colors. Verify with `print $terminfo[colors]`. |
| **A patched font** *(optional)* | Required only for the full range of icons and powerline symbols. See [Fonts](#4-fonts). |
| **Git** *(optional)* | Only needed if you want Git status in your prompt. Powerlevel10k ships a fast Git backend (`gitstatusd`) that it manages for you. |

> [!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](https://github.com/ryanoasis/nerd-fonts).

---

## 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

```zsh
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:
   ```zsh
   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
   ZSH_THEME="powerlevel10k/powerlevel10k"
   ```

### Other frameworks and plugin managers

=== "Prezto"

    Add to `~/.zpreztorc`:
    ```zsh
    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):
    ```zsh
    antigen theme romkatv/powerlevel10k
    ```

=== "Zinit"

    Add to `~/.zshrc`:
    ```zsh
    zinit ice depth=1; zinit light romkatv/powerlevel10k
    ```

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

| Manager | Line to add |
|---------|-------------|
| **Antibody** | `antibody bundle romkatv/powerlevel10k` |
| **Zplug** | `zplug romkatv/powerlevel10k, as:theme, depth:1` |
| **Zgen** | `zgen load romkatv/powerlevel10k powerlevel10k` |
| **Zplugin** | `zplugin ice depth=1; zplugin light romkatv/powerlevel10k` |
| **Zi** | `zi ice depth=1; zi light romkatv/powerlevel10k` |
| **Zap** | `plug "romkatv/powerlevel10k"` |

> [!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)"

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

=== "Arch Linux"

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

=== "Alpine Linux"

    ```zsh
    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](#cannot-make-powerlevel10k-work-with-my-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:
   ```sh
   uname -sm | tr '[A-Z]' '[a-z]'
   ```
   ```text
   linux x86_64
   ```
2. On an Internet-connected machine, fetch the matching binary into the clone:
   ```sh
   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:
   ```zsh
   echo 'source ~/powerlevel10k/powerlevel10k.zsh-theme' >>~/.zshrc
   ```
5. If `~/.zshrc` sets `ZSH_THEME`, remove that line:
   ```zsh
   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](https://github.com/romkatv/powerlevel10k-media/raw/master/MesloLGS%20NF%20Regular.ttf)
   - [MesloLGS NF Bold.ttf](https://github.com/romkatv/powerlevel10k-media/raw/master/MesloLGS%20NF%20Bold.ttf)
   - [MesloLGS NF Italic.ttf](https://github.com/romkatv/powerlevel10k-media/raw/master/MesloLGS%20NF%20Italic.ttf)
   - [MesloLGS NF Bold Italic.ttf](https://github.com/romkatv/powerlevel10k-media/raw/master/MesloLGS%20NF%20Bold%20Italic.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):

| Terminal | Where to set the font |
|----------|------------------------|
| **iTerm2** | *Preferences → Profiles → Text → Font* → `MesloLGS NF` (or let `p10k configure` do it) |
| **Apple Terminal** | *Preferences → Profiles → Text → Change* → `MesloLGS NF` |
| **GNOME Terminal** | *Preferences → (profile) → Text Appearance → Custom font* → `MesloLGS NF Regular` |
| **Konsole** | *Settings → Edit Current Profile → Appearance → Select Font* → `MesloLGS NF Regular` |
| **Windows Terminal** | *Settings → (profile/Defaults) → Appearance → Font face* → `MesloLGS NF` |
| **VS Code** | Set `terminal.integrated.fontFamily` to `MesloLGS NF` |

Config-file terminals:

=== "Alacritty (alacritty.toml)"

    ```toml
    [font.normal]
    family = "MesloLGS NF"
    ```

=== "kitty (kitty.conf)"

    ```text
    font_family MesloLGS NF
    ```

=== "WezTerm (wezterm.lua)"

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

=== "foot (foot.ini)"

    ```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:

```zsh
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.

| Style | Character |
|-------|-----------|
| **Lean** | Lightweight, no segment backgrounds. Saves two characters per segment versus Classic/Rainbow. Always includes the `prompt_char` symbol. Recommended starting point. |
| **Classic** | Segments on a subtle background with powerline separators. |
| **Rainbow** | Segments on vivid colored backgrounds. Confines colors to the terminal palette when you want theme-matched colors. |
| **Pure** | Exact replication of the [Pure](https://github.com/sindresorhus/pure) theme, for migrating Pure users. |

> [!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](#10-signature-features).
- **Transient prompt** — see [Signature Features](#10-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](#some-prompt-styles-are-missing-from-the-configuration-wizard).

---

## 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.

```zsh
p10k help
```

```text
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
```

| Command | What it does |
|---------|--------------|
| `p10k configure` | Launch the interactive [configuration wizard](#5-the-configuration-wizard). |
| `p10k reload` | Re-read configuration after you change `POWERLEVEL9K_*` parameters in a live shell. |
| `p10k segment ...` | Emit a [user-defined prompt segment](#12-writing-your-own-segment). Valid only while the prompt is rendering. |
| `p10k display ...` | Show, hide, or toggle prompt parts (lines, sides, frames, individual segments). |
| `p10k help [command]` | Print general help, or help for a specific command. |
| `p10k finalize` | Run the final initialization stage. Must be the very last line of `~/.zshrc` (used by the [instant prompt](#instant-prompt) flow). |

> [!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:

| Pattern | Selects |
|---------|---------|
| `empty_line` | the empty line between prompts |
| `ruler` | the ruler line |
| `N` | prompt line number N (1-based from the top, negative counts from the bottom) |
| `N/left`, `N/right` | the left / right prompt on line N |
| `N/left_frame`, `N/right_frame` | the frame on line N |
| `N/gap` | the gap between left and right prompts on line N |
| `N/left/S`, `N/right/S` | segment `S` (e.g. `dir`, `time`) on line N |
| `*/kubecontext` | every `kubecontext` segment, wherever it is |

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:**

```zsh
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:

```zsh
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](#8-prompt-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:

```zsh
source ~/.p10k.zsh
```

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

```zsh
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](#weird-things-happen-after-typing-source-zshrc).

> [!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

| Segment | Shows |
|---------|-------|
| `dir` | current working directory (smartly truncated — see [Signature Features](#current-directory-that-just-works)) |
| `vcs` | Git repository status (see [Reading Git Status](#9-reading-git-status)) |
| `prompt_char` | the prompt symbol; changes with Vi mode and turns red on error |
| `status` | exit code of the last command |
| `command_execution_time` | wall-clock duration of the last command |
| `time` | current time |
| `context` | `user@hostname` |
| `background_jobs` | presence of background jobs |
| `os_icon` | your OS logo |
| `vi_mode` | current Vi editing mode (unnecessary if you use `prompt_char`) |

### Language and version-manager segments

| Segment(s) | Source |
|-----------|--------|
| `node_version`, `nvm`, `nodenv`, `nodeenv` | Node.js version / environment managers |
| `pyenv`, `virtualenv`, `anaconda` | Python version / virtual environments |
| `go_version`, `goenv` | Go |
| `rust_version` | Rust (`rustc`) |
| `rbenv`, `rvm` | Ruby environment managers |
| `php_version`, `phpenv` | PHP |
| `java_version`, `jenv` | Java |
| `dotnet_version` | .NET |
| `laravel_version`, `package` | Laravel / `package.json` `name@version` |
| `perlbrew`, `plenv` | Perl |
| `luaenv`, `scalaenv`, `haskell_stack` | Lua / Scala / Haskell |
| `asdf`, `fvm` | asdf multi-tool / Flutter (fvm) |

### Cloud, infra, and tooling segments

| Segment(s) | Source |
|-----------|--------|
| `aws`, `aws_eb_env`, `azure`, `gcloud`, `google_app_cred` | Cloud provider profiles / credentials |
| `kubecontext` | current Kubernetes context |
| `terraform`, `terraform_version` | Terraform workspace / version |
| `nordvpn`, `vpn_ip`, `public_ip`, `ip`, `proxy`, `wifi` | Network state |
| `direnv`, `nix_shell`, `toolbox`, `chezmoi_shell` | Environment / shell context |
| `taskwarrior`, `timewarrior`, `todo` | Task and time tracking |
| `disk_usage`, `load`, `ram`, `swap`, `battery`, `cpu_arch` | System resources |
| `midnight_commander`, `nnn`, `lf`, `ranger`, `yazi`, `xplr`, `vim_shell` | File-manager / editor sub-shells |
| `per_directory_history` | per-directory history local/global indicator |

> [!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:

```text
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:

| Symbol | Meaning |
|--------|---------|
| `feature` | current branch; replaced with `#tag` or `@commit` if not on a branch |
| `master` | remote tracking branch; shown only if different from the local branch |
| `wip` | the latest commit's summary contains "wip" or "WIP" |
| `=` | up to date with the remote (neither ahead nor behind) |
| `⇣42` | 42 commits **behind** the remote |
| `⇡42` | 42 commits **ahead** of the remote |
| `⇠42` | 42 commits behind the **push** remote |
| `⇢42` | 42 commits ahead of the **push** remote |
| `*42` | 42 stashes |
| `merge` | repository state (e.g. a merge or rebase in progress) |
| `~42` | 42 merge conflicts |
| `+42` | 42 staged changes |
| `!42` | 42 unstaged changes |
| `?42` | 42 untracked files |
| `─` | the count of staged/unstaged/untracked files is unknown (large repo — see below) |

> [!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`:

```zsh
# 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`:

| Value | Behavior |
|-------|----------|
| `verbose` *(default)* | warn when console output is detected during init |
| `quiet` | allow console output, suppress the warning |
| `off` | disable instant prompt entirely |

> [!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`:

```zsh
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](#11-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](https://github.com/Powerlevel9k/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](https://github.com/sindresorhus/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:

```zsh
# 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`.

```zsh
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:

```zsh
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:

```zsh
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`](https://github.com/romkatv/powerlevel10k/blob/master/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:**

```zsh
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:

```zsh
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:

| Option | Meaning |
|--------|---------|
| `-t text` | the segment's main content (undergoes prompt expansion) |
| `-i icon` | the segment's icon |
| `-r` / `+r` | icon is a symbolic reference to resolve (e.g. `LOCK_ICON`) / icon is literal (default) |
| `-b bg` | background color (`blue`, `4`, or `#0000ff`; empty = transparent) |
| `-f fg` | foreground color (empty = default foreground) |
| `-s state` | a state name used to select styling overrides |
| `-c cond` | condition; if it expands to empty, the segment is hidden (advanced) |
| `-e` / `+e` | content should / should not undergo parameter expansion and process substitution (advanced) |
| `-h` | print help |

> [!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`.

| Installation | Update command |
|--------------|----------------|
| Manual | `git -C ~/powerlevel10k pull` |
| Oh My Zsh | `git -C "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k" pull` |
| Prezto | `zprezto-update` |
| Zim | `zimfw update` |
| Antigen | `antigen update` |
| Antidote | `antidote update` |
| Zinit | `zinit update` |
| Homebrew | `brew update && brew upgrade` |
| Arch Linux | `yay -S --noconfirm zsh-theme-powerlevel10k-git` |
| Alpine Linux | `apk update && apk upgrade` |

### 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:
   ```zsh
   grep -E 'p10k|powerlevel10k' ~/.zshrc ~/.zpreztorc ~/.zimrc 2>/dev/null
   ```
4. Delete your config file:
   ```zsh
   rm -f ~/.p10k.zsh
   ```
5. Delete the source files (manual install shown; use the uninstall command for your
   manager otherwise):
   ```zsh
   rm -rf ~/powerlevel10k
   ```
6. Restart Zsh (`exec zsh`).
7. Delete cache files:
   ```zsh
   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:
```zsh
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:
  ```zsh
  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](#4-fonts), 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`:
```zsh
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`:
```zsh
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](https://sw.kovidgoyal.net/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:
  ```zsh
  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.:
```zsh
typeset -g POWERLEVEL9K_OS_ICON_CONTENT_EXPANSION='${P9K_CONTENT} '  # extra space
```

### Incorrect Git status in prompt

**Cause:** The Git backend uses [libgit2](https://github.com/libgit2/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](#9-reading-git-status) — 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](https://github.com/romkatv/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](#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](https://github.com/romkatv/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](#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:
```zsh
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](#extra-or-missing-spaces-compared-to-powerlevel9k)
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:
```zsh
(( ${+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](https://github.com/romkatv/powerlevel10k/issues) (best), or use
[Gitter](https://gitter.im/powerlevel10k/community). 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](https://github.com/romkatv/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

| Command | Purpose |
|---------|---------|
| `p10k configure` | run the configuration wizard |
| `p10k reload` | reload config after live `POWERLEVEL9K_*` changes |
| `p10k display PART=STATE` | show/hide/toggle a prompt part |
| `p10k help [command]` | print help |
| `exec zsh` | restart Zsh (apply changes safely) |
| `source ~/.p10k.zsh` | apply config-file edits to the current shell |

### Key files

| Path | Role |
|------|------|
| `~/.p10k.zsh` | your prompt configuration (created by the wizard) |
| `~/.zshrc` | sources the theme and your config; holds the instant-prompt block |
| `powerlevel10k.zsh-theme` | the theme entry point you `source` |
| `${XDG_CACHE_HOME:-$HOME/.cache}/p10k-*` | cache files (safe to delete) |
| `${XDG_CACHE_HOME:-$HOME/.cache}/gitstatus` | downloaded `gitstatusd` binary |

### Key parameters

| Parameter | Effect |
|-----------|--------|
| `POWERLEVEL9K_LEFT_PROMPT_ELEMENTS` | segments shown on the left |
| `POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS` | segments shown on the right |
| `POWERLEVEL9K_MODE` | icon set (`nerdfont-v3`, `ascii`, `compatible`, …) |
| `POWERLEVEL9K_INSTANT_PROMPT` | `verbose` / `quiet` / `off` |
| `POWERLEVEL9K_<SEGMENT>_SHOW_ON_COMMAND` | show a segment only for matching commands |
| `POWERLEVEL9K_<SEGMENT>_FOREGROUND` / `_BACKGROUND` | segment colors |
| `POWERLEVEL9K_DISABLE_HOT_RELOAD` | set `false` to apply live edits without `p10k reload` |
| `POWERLEVEL9K_VCS_DISABLED_WORKDIR_PATTERN` | suppress `vcs` in matching directories |
| `ZLE_RPROMPT_INDENT=0` | flush the right prompt to the screen edge |

### 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)

---

_Generated June 2026 from romkatv/powerlevel10k at a0c9dbe. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._