Configuration variables

ABBR_AUTOLOADintegerIf non-zero, automatically account for updates to the user abbreviations file (see Storage and manual editing)1
ABBR_DEBUGintegerIf non-zero, print debugging messages0
ABBR_DEFAULT_BINDINGSintegerIf non-zero, add the default bindings (see Widgets and key bindings)1
ABBR_DRY_RUNintegerIf non-zero, use dry run mode without passing --dry-run0
ABBR_FORCEintegerIf non-zero, use force mode without passing --force (see Usage > Commands > add)0
ABBR_PRECMD_LOGSinteger⚠️ DEPRECATED ⚠️ If non-zero, support precmd logs, for example to warn that a deprecated widget was used1
ABBR_QUIETintegerIf non-zero, use quiet mode without passing --quiet0
ABBR_QUIETERintegerIf non-zero, use quieter mode without passing --quieter0
ABBR_TMPDIRStringPath to the directory temporary files are stored in. Ends in /${${TMPDIR:-/tmp}%/}/zsh-abbr/

If changing this, you may want to delete the default directory.
ABBR_USER_ABBREVIATIONS_FILEStringPath to the file user abbreviation are stored in (see Storage and manual editing)${XDG_CONFIG_HOME:-$HOME/.config}/zsh-abbr/user-abbreviations

with legacy support for using ${XDG_CONFIG_HOME:-$HOME/.config}/zsh/abbreviations instead if a file exists at that path

If changing this, you may want to delete the default file.
NO_COLORmixedIf set (to any value or no value at all) abbr will not use color in its output. See

Exported variables

In addition to exporting the configuration variables above, zsh-abbr creates the following variables:

ABBR_GLOBAL_SESSION_ABBREVIATIONSassociative arrayThe global session abbreviations
ABBR_GLOBAL_USER_ABBREVIATIONSassociative arrayThe global user abbreviations
ABBR_PRECMD_MESSAGEprompt string⚠️ DEPRECATED ⚠️ Message shown by precmd hook if ABBR_PRECMD_LOGS is non-zero
ABBR_REGULAR_SESSION_ABBREVIATIONSassociative arrayThe regular session abbreviations
ABBR_SOURCE_PATHstringPath to the zsh-abbr.zsh
ABBR_REGULAR_USER_ABBREVIATIONSassociative arrayThe regular user abbreviations

Each element in ABBR_GLOBAL_SESSION_ABBREVIATIONS, ABBR_GLOBAL_USER_ABBREVIATIONS, ABBR_REGULAR_SESSION_ABBREVIATIONS, and ABBR_REGULAR_USER_ABBREVIATIONS has the form ABBREVIATION=EXPANSION. The expansion value is quoted. Scripters will probably want to remove one level of quotes, using the Q modifier (e.g. for v in ${(Qv)ABBR_REGULAR_USER_ABBREVIATIONS}...).

Transient exported variables

zsh-abbr exports the following variables in limited contexts:

ABBR_INITIALIZINGintegerSet to 1 when zsh-abbr is initializing, otherwise not set
ABBR_LOADING_USER_ABBREVIATIONSintegerSet to 1 when the interactive shell is refreshing its list of user abbreviations, otherwise not set

Storage and manual editing

User abbreviations live in a plain text file which you can edit directly, share, keep in version control, etc. Abbreviations in this file are loaded when each new session is opened; non-abbr commands will be ignored and then excised from the file.

zsh-abbr automatically keeps the user abbreviations storage file alphabetized, with all global user abbreviations before the first regular user abbreviation.

Every time an abbr command is run, the session's updates its user abbreviations with the latest from the user abbreviations file. This should add no appreciable time, but you prefer it can be turned off by setting ABBR_AUTOLOAD=0.

To refresh the user abbreviations from the user abbreviation, run abbr load (or any other abbr command).

Widgets and key bindings

By default

  • Space expands abbreviations
  • CtrlSpace is a normal space
  • Enter expands and accepts abbreviations

(In incremental search mode, Space is a normal space and CtrlSpace expands abbreviations.)

There are three available widgets:

WidgetBehaviorDefault binding
abbr-expandIf following an abbreviation, expands itNot bound
abbr-expand-and-acceptIf following an abbreviation, expands it; then accepts the lineEnter (" ")
abbr-expand-and-spaceIf following an abbreviation, expands it; then adds a spaceSpace ("^ "); in search mode, Ctrl Space (-M isearch "^ ")

zsh-abbr also binds Ctrl Space ("^ ") to magic-space and, in search mode, Space (-M isearch " ") to magic-space.

In the following example, additional bindings are added such that Ctrle expands abbreviations without adding a trailing space and Ctrla has the same behavior as Space.

% cat ~/.zshrc
# -- snip --
bindkey "^E" abbr-expand
bindkey "^A" abbr-expand-and-space
# -- snip --


To prevent the creation of the default bindings, set ABBR_DEFAULT_BINDINGS to 0 before initializing zsh-abbr. In the following example, CtrlSpace expands abbreviations and Space is not bound to any zsh-abbr widget.

% cat ~/.zshrc
# -- snip --
bindkey "^ " abbr-expand-and-space
# -- snip --
# load zsh-abbr
# -- snip --


Alternative keymaps

By default, zsh-abbr is only enabled for the default keymap. To enable a widget for another keymap, run bindkey -M. For example, the following extends zsh-abbr's default behavior to the viins keymap:

bindkey -M viins " " abbr-expand-and-space
bindkey -M viins "^ " magic-space
bindkey -M viins "^M" abbr-expand-and-accept



These integrations are not regularly tested. It is possible that they are out of date. Pull requests are welcome to fix broken integrations. The zsh-abbr maintainer does not commit to keeping them working — if something breaks and the maintainer and the community does not have a fix, it may be removed from this documentation.

Syntax highlighting


To highlight user abbreviations that will expand, fast-syntax-highlighting users can add these lines to .zshrc below where zsh-abbr and all abbreviations are loaded.

Known limitation: the following fast-syntax-highlighting solution only supports single-word abbreviations. 🌟 Want highlighting for multi-word abbreviations? See zsh-abbr#24.

chroma_single_word() {
  (( next_word = 2 | 8192 ))

  local __first_call="$1" __wrd="$2" __start_pos="$3" __end_pos="$4"
  local __style

  (( __first_call )) && { __style=${FAST_THEME_NAME}alias }
  [[ -n "$__style" ]] && (( __start=__start_pos-${#PREBUFFER}, __end=__end_pos-${#PREBUFFER}, __start >= 0 )) && reply+=("$__start $__end ${FAST_HIGHLIGHT_STYLES[$__style]}")

  (( this_word = next_word ))

  return 0

register_single_word_chroma() {
  local word=$1
  if [[ -x $(command -v $word) ]] || [[ -n $FAST_HIGHLIGHT["chroma-$word"] ]]; then
    return 1

  FAST_HIGHLIGHT+=( "chroma-$word" chroma_single_word )
  return 0

if [[ -n $FAST_HIGHLIGHT ]]; then
  for abbr in ${(f)"$(abbr list-abbreviations)"}; do
    if [[ $abbr != *' '* ]]; then
      register_single_word_chroma ${(Q)abbr}


To highlight user abbreviations that will expand, zsh-syntax-highlighting users can add these lines to .zshrc below where zsh-abbr is loaded. For more info see the zsh-syntax-highlighting regexp highlighter documentation.

Replace <styles for global abbreviations> with a zsh character highlighting string (start at "The available types of highlighting are the following."). For example fg=blue, fg=blue,bg=red,bold, etc.

Known limitation: the following zsh-syntax-highlighting solutions do not support unmatched parentheses within abbreviations. For example the valid abbr '('='(x' will make zsh-syntax-highlighting error. 🌟 Have a better solution? Please contribute it!


ZSH_HIGHLIGHT_REGEXP+=('^[[:blank:][:space:]]*('${(j:|:)${(Qk)ABBR_REGULAR_USER_ABBREVIATIONS}}')$' <styles for regular abbreviations>)
ZSH_HIGHLIGHT_REGEXP+=('\<('${(j:|:)${(Qk)ABBR_GLOBAL_USER_ABBREVIATIONS}}')$' <styles for global abbreviations>)


ZSH_HIGHLIGHT_REGEXP=('^[[:blank:][:space:]]*('${(j:|:)${(Qk)ABBR_REGULAR_USER_ABBREVIATIONS}}')$' <styles for regular abbreviations>)
ZSH_HIGHLIGHT_REGEXP+=('[[:<:]]('${(j:|:)${(Qk)ABBR_GLOBAL_USER_ABBREVIATIONS}}')$' <styles for global abbreviations>)

After adding the snippets, all new terminals will use them. To use them in an already-open terminal, restart zsh in that terminal:

exec zsh

vi mode

Switching to vi mode —with bindkey -v or software which calls bindkey -v — will wipe out the keybindings zsh-abbr's interactive behavior relies on. If you use vi mode, enable it before initializing zsh-abbr.

# .zshrc

bindkey -v
# load zsh-abbr here


macOS System Text Substitutions

Add the following snippet to your .zshrc file to create abbreviation for all macOS text substitutions.

for substitution in ${(f)"$(defaults read ~/Library/Preferences/.GlobalPreferences.plist NSUserDictionaryReplacementItems | plutil -convert json -o - - | jq -r 'to_entries[] | "\(.value.replace)=\(.value.with)"')"}; do
  abbr add [options] "$substitution"