zsh-syntax-highlighting Documentation

Fish shell like syntax highlighting for Zsh.

22,913 stars Shell Shell 1 file · ~5,390 tokens #screenshot#shell#syntax-highlighting#zsh#zsh-syntax-highlighting
RAW Doc

File: README.md

zsh-syntax-highlighting [![Build Status][build-status-image]][build-status]

Fish shell-like syntax highlighting for Zsh.

Requirements: zsh 4.3.11+.

This package provides syntax highlighting for the shell zsh. It enables
highlighting of commands whilst they are typed at a zsh prompt into an
interactive terminal. This helps in reviewing commands before running
them, particularly in catching syntax errors.

Some examples:

Before:

After: 

Before:

After: 

Before:

After: 

Before:

After: 

How to install

See INSTALL.md.

FAQ

Why must `zsh-syntax-highlighting.zsh` be sourced at the end of the `.zshrc` file?

zsh-syntax-highlighting works by hooking into the Zsh Line Editor (ZLE) and
computing syntax highlighting for the command-line buffer as it stands at the
time z-sy-h's hook is invoked.

In zsh 5.2 and older,
zsh-syntax-highlighting.zsh hooks into ZLE by wrapping ZLE widgets. It must
be sourced after all custom widgets have been created (i.e., after all zle -N
calls and after running compinit) in order to be able to wrap all of them.
Widgets created after z-sy-h is sourced will work, but will not update the
syntax highlighting.

In zsh newer than 5.8 (not including 5.8 itself),
zsh-syntax-highlighting uses the add-zle-hook-widget facility to install
a zle-line-pre-redraw hook. Hooks are run in order of registration,
therefore, z-sy-h must be sourced (and register its hook) after anything else
that adds hooks that modify the command-line buffer.

Highlighting the command line during an incremental history search (by default bound to
to Ctrl+R in zsh's emacs keymap) requires zsh 5.4 or newer.

Under zsh versions older than 5.4, the zsh-default underlining
of the matched portion of the buffer remains available, but zsh-syntax-highlighting's
additional highlighting is unavailable. (Those versions of zsh do not provide
enough information to allow computing the highlighting correctly.)

See issues #288 and #415 for details.

How are new releases announced?

There is currently no "push" announcements channel. However, the following
alternatives exist:

How to tweak

Syntax highlighting is done by pluggable highlighter scripts. See the
documentation on highlighters for details and
configuration settings.

File: docs/highlighters/brackets.md

zsh-syntax-highlighting / highlighters / brackets

This is the brackets highlighter, that highlights brackets and parentheses, and
matches them.

How to tweak it

This highlighter defines the following styles:

  • bracket-error - unmatched brackets
  • bracket-level-N - brackets with nest level N
  • cursor-matchingbracket - the matching bracket, if cursor is on a bracket

To override one of those styles, change its entry in ZSH_HIGHLIGHT_STYLES,
for example in ~/.zshrc:

zsh
# To define styles for nested brackets up to level 4
ZSH_HIGHLIGHT_STYLES[bracket-level-1]='fg=blue,bold'
ZSH_HIGHLIGHT_STYLES[bracket-level-2]='fg=red,bold'
ZSH_HIGHLIGHT_STYLES[bracket-level-3]='fg=yellow,bold'
ZSH_HIGHLIGHT_STYLES[bracket-level-4]='fg=magenta,bold'

The syntax for values is the same as the syntax of "types of highlighting" of
the zsh builtin $zle_highlight array, which is documented in the zshzle(1)
manual page.

File: docs/highlighters/cursor.md

zsh-syntax-highlighting / highlighters / cursor

This is the cursor highlighter, that highlights the cursor.

How to tweak it

This highlighter defines the following styles:

  • cursor - the style for the current cursor position

To override one of those styles, change its entry in ZSH_HIGHLIGHT_STYLES,
for example in ~/.zshrc:

zsh
ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue'

The syntax for values is the same as the syntax of "types of highlighting" of
the zsh builtin $zle_highlight array, which is documented in the zshzle(1)
manual page.

File: docs/highlighters/line.md

zsh-syntax-highlighting / highlighters / line

This is the line highlighter, that highlights the whole line.

How to tweak it

This highlighter defines the following styles:

  • line - the style for the whole line

To override one of those styles, change its entry in ZSH_HIGHLIGHT_STYLES,
for example in ~/.zshrc:

zsh
ZSH_HIGHLIGHT_STYLES[line]='bold'

The syntax for values is the same as the syntax of "types of highlighting" of
the zsh builtin $zle_highlight array, which is documented in the zshzle(1)
manual page.

File: docs/highlighters/main.md

zsh-syntax-highlighting / highlighters / main

This is the main highlighter, that highlights:

  • Commands
  • Options
  • Arguments
  • Paths
  • Strings

This highlighter is active by default.

How to tweak it

This highlighter defines the following styles:

  • unknown-token - unknown tokens / errors
  • reserved-word - shell reserved words (if, for)
  • alias - aliases
  • suffix-alias - suffix aliases (requires zsh 5.1.1 or newer)
  • global-alias - global aliases
  • builtin - shell builtin commands (shift, pwd, zstyle)
  • function - function names
  • command - command names
  • precommand - precommand modifiers (e.g., noglob, builtin)
  • commandseparator - command separation tokens (;, &&)
  • hashed-command - hashed commands
  • autodirectory - a directory name in command position when the AUTO_CD option is set
  • path - existing filenames
  • path_pathseparator - path separators in filenames (/); if unset, path is used (default)
  • path_prefix - prefixes of existing filenames
  • path_prefix_pathseparator - path separators in prefixes of existing filenames (/); if unset, path_prefix is used (default)
  • globbing - globbing expressions (*.txt)
  • history-expansion - history expansion expressions (!foo and ^foo^bar)
  • command-substitution - command substitutions ($(echo foo))
  • command-substitution-unquoted - an unquoted command substitution ($(echo foo))
  • command-substitution-quoted - a quoted command substitution ("$(echo foo)")
  • command-substitution-delimiter - command substitution delimiters ($( and ))
  • command-substitution-delimiter-unquoted - an unquoted command substitution delimiters ($( and ))
  • command-substitution-delimiter-quoted - a quoted command substitution delimiters ("$( and )")
  • process-substitution - process substitutions (<(echo foo))
  • process-substitution-delimiter - process substitution delimiters (<( and ))
  • arithmetic-expansion - arithmetic expansion $(( 42 )))
  • single-hyphen-option - single-hyphen options (-o)
  • double-hyphen-option - double-hyphen options (--option)
  • back-quoted-argument - backtick command substitution (`foo`)
  • back-quoted-argument-unclosed - unclosed backtick command substitution (`foo)
  • back-quoted-argument-delimiter - backtick command substitution delimiters (`)
  • single-quoted-argument - single-quoted arguments ('foo')
  • single-quoted-argument-unclosed - unclosed single-quoted arguments ('foo)
  • double-quoted-argument - double-quoted arguments ("foo")
  • double-quoted-argument-unclosed - unclosed double-quoted arguments ("foo)
  • dollar-quoted-argument - dollar-quoted arguments ($'foo')
  • dollar-quoted-argument-unclosed - unclosed dollar-quoted arguments ($'foo)
  • rc-quote - two single quotes inside single quotes when the RC_QUOTES option is set ('foo''bar')
  • dollar-double-quoted-argument - parameter expansion inside double quotes ($foo inside "")
  • back-double-quoted-argument - backslash escape sequences inside double-quoted arguments (\" in "foo\"bar")
  • back-dollar-quoted-argument - backslash escape sequences inside dollar-quoted arguments (\x in $'\x48')
  • assign - parameter assignments (x=foo and x=( ))
  • redirection - redirection operators (<, >, etc)
  • comment - comments, when setopt INTERACTIVE_COMMENTS is in effect (echo # foo)
  • comment - elided parameters in command position ($x ls when $x is unset or empty)
  • named-fd - named file descriptor (the fd in echo foo {fd}>&2)
  • numeric-fd - numeric file descriptor (the 2 in echo foo {fd}>&2)
  • arg0 - a command word other than one of those enumerated above (other than a command, precommand, alias, function, or shell builtin command).
  • default - everything else

To override one of those styles, change its entry in ZSH_HIGHLIGHT_STYLES,
for example in ~/.zshrc:

zsh
# Declare the variable
typeset -A ZSH_HIGHLIGHT_STYLES

# To differentiate aliases from other command types
ZSH_HIGHLIGHT_STYLES[alias]='fg=magenta,bold'

# To have paths colored instead of underlined
ZSH_HIGHLIGHT_STYLES[path]='fg=cyan'

# To disable highlighting of globbing expressions
ZSH_HIGHLIGHT_STYLES[globbing]='none'

The syntax for values is the same as the syntax of "types of highlighting" of
the zsh builtin $zle_highlight array, which is documented in the zshzle(1)
manual page.

Parameters

To avoid partial path lookups on a path, add the path to the ZSH_HIGHLIGHT_DIRS_BLACKLIST array.

zsh
ZSH_HIGHLIGHT_DIRS_BLACKLIST+=(/mnt/slow_share)

Useless trivia

Forward compatibility.

zsh-syntax-highlighting attempts to be forward-compatible with zsh.
Specifically, we attempt to facilitate highlighting command word types that
had not yet been invented when this version of zsh-syntax-highlighting was
released.

A command word is something like a function name, external command name, et
cetera. (See
Simple Commands & Pipelines in zshmisc(1)
for a formal definition.)

If a new kind of command word is ever added to zsh — something conceptually
different than "function" and "alias" and "external command" — then command words
of that (new) kind will be highlighted by the style arg0_$kind,
where $kind is the output of type -w on the new kind of command word. If that
style is not defined, then the style arg0 will be used instead.

File: docs/highlighters/pattern.md

zsh-syntax-highlighting / highlighters / pattern

This is the pattern highlighter, that highlights user-defined patterns.

How to tweak it

To use this highlighter, associate patterns with styles in the
ZSH_HIGHLIGHT_PATTERNS associative array, for example in ~/.zshrc:

zsh
# Declare the variable
typeset -A ZSH_HIGHLIGHT_PATTERNS

# To have commands starting with `rm -rf` in red:
ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')

The syntax for values is the same as the syntax of "types of highlighting" of
the zsh builtin $zle_highlight array, which is documented in the zshzle(1)
manual page.

File: docs/highlighters/regexp.md

zsh-syntax-highlighting / highlighters / regexp

This is the regexp highlighter, that highlights user-defined regular
expressions. It's similar to the pattern highlighter, but allows more complex
patterns.

How to tweak it

To use this highlighter, associate regular expressions with styles in the
ZSH_HIGHLIGHT_REGEXP associative array, for example in ~/.zshrc:

zsh
typeset -A ZSH_HIGHLIGHT_REGEXP
ZSH_HIGHLIGHT_REGEXP+=('^rm .*' fg=red,bold)

This will highlight lines that start with a call to the rm command.

The regular expressions flavour used is PCRE when the
RE_MATCH_PCRE option is set and POSIX Extended Regular Expressions (ERE),
as implemented by the platform's C library, otherwise. For details on the
latter, see the zsh/regex module's documentation and the
regcomp(3) and re_format(7) manual pages on your system.

For instance, to highlight sudo only as a complete word, i.e., sudo cmd,
but not sudoedit, one might use:

  • When the RE_MATCH_PCRE is set:

    zsh
    typeset -A ZSH_HIGHLIGHT_REGEXP
ZSH_HIGHLIGHT_REGEXP+=('\bsudo\b' fg=123,bold)

  • When the RE_MATCH_PCRE is unset, on platforms with GNU libc (e.g., many GNU/Linux distributions):

    zsh
    typeset -A ZSH_HIGHLIGHT_REGEXP
ZSH_HIGHLIGHT_REGEXP+=('\<sudo\>' fg=123,bold)

  • When the RE_MATCH_PCRE is unset, on BSD-based platforms (e.g., macOS):

    zsh
    typeset -A ZSH_HIGHLIGHT_REGEXP
ZSH_HIGHLIGHT_REGEXP+=('[[:<:]]sudo[[:>:]]' fg=123,bold)

Note, however, that PCRE and POSIX ERE have a large common subset:
for instance, the regular expressions [abc], a*, and (a|b) have the same
meaning in both flavours.

The syntax for values is the same as the syntax of "types of highlighting" of
the zsh builtin $zle_highlight array, which is documented in the zshzle(1)
manual page.

See also: regular expressions tutorial, zsh regexp operator =~
in the zshmisc(1) manual page

File: docs/highlighters/root.md

zsh-syntax-highlighting / highlighters / root

This is the root highlighter, that highlights the whole line if the current
user is root.

How to tweak it

This highlighter defines the following styles:

  • root - the style for the whole line if the current user is root.

To override one of those styles, change its entry in ZSH_HIGHLIGHT_STYLES,
for example in ~/.zshrc:

zsh
ZSH_HIGHLIGHT_STYLES[root]='bg=red'

The syntax for values is the same as the syntax of "types of highlighting" of
the zsh builtin $zle_highlight array, which is documented in the zshzle(1)
manual page.

File: docs/highlighters.md

zsh-syntax-highlighting / highlighters

Syntax highlighting is done by pluggable highlighters:

Highlighter-independent settings

By default, all command lines are highlighted. However, it is possible to
prevent command lines longer than a fixed number of characters from being
highlighted by setting the variable ${ZSH_HIGHLIGHT_MAXLENGTH} to the maximum
length (in characters) of command lines to be highlighter. This is useful when
editing very long command lines (for example, with the fned utility
function). Example:

zsh
ZSH_HIGHLIGHT_MAXLENGTH=512

How to activate highlighters

To activate an highlighter, add it to the ZSH_HIGHLIGHT_HIGHLIGHTERS array.
By default ZSH_HIGHLIGHT_HIGHLIGHTERS is (main). For example to activate
brackets, pattern, and cursor highlighters, in ~/.zshrc do:

zsh
ZSH_HIGHLIGHT_HIGHLIGHTERS+=(brackets pattern cursor)

How to tweak highlighters

Highlighters look up styles from the ZSH_HIGHLIGHT_STYLES associative array.
Navigate into the individual highlighters' documentation to
see what styles (keys) each highlighter defines; the syntax for values is the
same as the syntax of "types of highlighting" of the zsh builtin
$zle_highlight array, which is documented in the zshzle(1) manual
page.

Some highlighters support additional configuration parameters; see each
highlighter's documentation for details and examples.

How to implement a new highlighter

To create your own acme highlighter:

  • Create your script at
    highlighters/acme/acme-highlighter.zsh.

  • Implement the _zsh_highlight_highlighter_acme_predicate function.
    This function must return 0 when the highlighter needs to be called and
    non-zero otherwise, for example:

    zsh
    _zsh_highlight_highlighter_acme_predicate() {
  # Call this highlighter in SVN working copies
  [[ -d .svn ]]
}

  • Implement the _zsh_highlight_highlighter_acme_paint function.
    This function does the actual syntax highlighting, by calling
    _zsh_highlight_add_highlight with the start and end of the region to
    be highlighted and the ZSH_HIGHLIGHT_STYLES key to use. Define the default
    style for that key in the highlighter script outside of any function with
    : ${ZSH_HIGHLIGHT_STYLES[key]:=value}, being sure to prefix
    the key with your highlighter name and a colon. For example:

    zsh
    : ${ZSH_HIGHLIGHT_STYLES[acme:aurora]:=fg=green}

_zsh_highlight_highlighter_acme_paint() {
  # Colorize the whole buffer with the 'aurora' style
  _zsh_highlight_add_highlight 0 $#BUFFER acme:aurora
}

    If you need to test which options the user has set, test zsyh_user_options
    with a sensible default if the option is not present in supported zsh
    versions. For example:

    zsh
    [[ ${zsyh_user_options[ignoreclosebraces]:-off} == on ]]

    The option name must be all lowercase with no underscores and not an alias.

  • Name your own functions and global variables _zsh_highlight_acme_*.

    • In zsh-syntax-highlighting 0.4.0 and earlier, the entrypoints
      _zsh_highlight_highlighter_acme_predicate and
      _zsh_highlight_highlighter_acme_paint
      were named
      _zsh_highlight_acme_highlighter_predicate and
      _zsh_highlight_highlighter_acme_paint respectively.

      These names are still supported for backwards compatibility;
      however, support for them will be removed in a future major or minor release (v0.x.0 or v1.0.0).

  • Activate your highlighter in ~/.zshrc:

    zsh
    ZSH_HIGHLIGHT_HIGHLIGHTERS+=(acme)

  • Write tests.

File: highlighters/README.md

zsh-syntax-highlighting / highlighters

Navigate into the individual highlighters' documentation to see
what styles ($ZSH_HIGHLIGHT_STYLES keys) each highlighter defines.

Refer to the documentation on highlighters for further
information.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#screenshot Browse screenshot catalog → #shell Browse shell catalog → #syntax-highlighting Browse syntax-highlighting catalog → #zsh Browse zsh catalog → #zsh-syntax-highlighting Browse zsh-syntax-highlighting catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →