Skip to main content

⚡️ Installation

Automated setup​

tip
  • Verify the sha256 checksum for file: public/sh/install.sh
  • If required append -b <tag> or -b <branch> e.g:
sh -c "$(curl -fsSL get.zshell.dev)" -- -b main

The normal default command runs the guided loader profile. The install.sh script is standalone: when sibling assets are unavailable, it downloads setup.sh, profiles.tsv, init.zsh, and checksum.txt from the selected ZI_SRC_REF (defaulting to main), then verifies every companion asset against that matching checksum manifest before plan/apply. The repository does not need to be cloned.

Install and include the guided loader configuration in .zshrc:

sh -c "$(curl -fsSL get.zshell.dev)" --

Passing -a loader is equivalent because the loader profile is the default.

The installer creates the loader configuration under $XDG_CONFIG_HOME/zi (defaulting to ~/.config/zi) and adds only this managed block to .zshrc:

~/.zshrc
# >>> zi setup >>>
source '/absolute/config/zi/setup.zsh'
# <<< zi setup <<<

The generated setup.zsh entrypoint owns pre-settings (setup/pre.zsh), loader/zzinit (init.zsh and zzinit), recipes (setup/shell.zsh), and diagnostics.

Then reload the shell with: exec zsh. All done!

:::info Compatibility and migration

  • Direct profile deprecation: The legacy direct zi.zsh profile (-a direct) is deprecated in install.sh. Passing -a direct emits a warning and uses the guided loader profile instead.
  • Automatic migration: If .zshrc contains an existing legacy direct, loader, or annex/zunit block, the installer automatically detects and migrates it to the managed setup.zsh block without evaluating untrusted shell code.
  • Unrecognised integrations: If an unrecognised Zi integration remains in .zshrc, the installer safely refuses to proceed to avoid duplicate initialization.

:::

:::note Automation and TUI

For automation or terminal interfaces driving setup.sh, the additive setup.sh apply --events DIR option is optional. It creates a private new absolute directory and publishes atomic numbered zi-setup-event-v1 event directories with started and terminal state for active operations. Human stdout/stderr remains for people rather than machine decisions. Consumers must treat process completion as authoritative and tolerate a missing terminal event if a cancellation signal interrupts event publication itself; staging cleanup and exit 6 still apply.

:::

Manual Setup​

Related

Prepare​

Set up the install location and create a directory:

The assignment below explicitly selects a fresh XDG-style home. It does not migrate an existing $HOME/.zi installation. For automatic legacy detection, use the loader above or source your existing Zi checkout without overriding ZI[HOME_DIR].

typeset -Ag ZI
if [[ -n ${XDG_DATA_HOME:-} && $XDG_DATA_HOME == /* ]]; then
  ZI[HOME_DIR]="$XDG_DATA_HOME/zi"
else
  ZI[HOME_DIR]="$HOME/.local/share/zi"
fi
ZI[BIN_DIR]="${ZI[HOME_DIR]}/bin"
command mkdir -p -- "${ZI[BIN_DIR]}"

For security reasons run function compaudit to check if the completion system would use files owned by root or by the current user, or files in directories that are world or group-writable.

If failed, then set the current user as the owner of directories, then remove group/others write permissions, and clone the repository:

compaudit | xargs chown -R "$(whoami)" "${ZI[HOME_DIR]}"
compaudit | xargs chmod -R go-w "${ZI[HOME_DIR]}"
command git clone https://github.com/z-shell/zi.git "${ZI[BIN_DIR]}"

Enable​

To enable Zi, source the zi.zsh from the previously set up directory placing the following snippet in the .zshrc file:

~/.zshrc
typeset -A ZI
: ${ZI[HOME_DIR]:="${XDG_DATA_HOME:-${HOME}/.local/share}/zi"}
: ${ZI[BIN_DIR]:="${ZI[HOME_DIR]}/bin"}
source "${ZI[BIN_DIR]}/zi.zsh"

Completions​

Enable Zi completions by placing the following snippet in the .zshrc file:

caution

The snippet below must be placed after after enabling Zi.

~/.zshrc
autoload -Uz _zi
(( ${+_comps} )) && _comps[zi]=_zi

Post-install​

After a fresh install, it is recommended to reload the shell and recompile Zi with:

  • exec zsh -il
  • zi self-update

Run zi -h for available commands or explore wiki to extend, customize and create 👍 🎉.

If you have any issue or need help 🤦‍♂️, lets discuss it or open an issue on GitHub.

It helps us to improve and make Zi better. Don't forget to help the project: share, contribute, or translate 🌐 🥰 🤓.

Let's glue a toolchain that works for us 🚀.

Have ideas?​

 Suggest or request at playground​

sh -c "$(curl -fsSL get.zshell.dev)" -- -a ???

 Need warm-up?​

 Docker Alpine​

docker run --rm -it ghcr.io/z-shell/zd:latest

Turbo Zi in Docker​

If you create a Docker image that uses Zi, install Turbo-loaded plugins before the shell starts interactively, with the @zi-scheduler function in such a way, that it:

  • Install plugins without waiting for the prompt (i.e. it's script friendly).
  • Install all plugins instantly, without respecting the wait argument.

To accomplish this, use burst argument and call the @zi-scheduler function:

RUN zsh -i -c -- '@zi-scheduler burst || true'

Zi Module: zpmod​

The module transparently and automatically compiles sourced scripts and lists of all sourced files with the time the sourcing took in milliseconds on the left.

Status page ✅

Installer​

ServiceURL
Short URLhttps://get.zshell.dev
GitHub RAWhttps://raw.githubusercontent.com/z-shell/src/main/public/sh/install.sh

Loader​

ServiceURL
Short URLhttps://init.zshell.dev
GitHub RAWhttps://raw.githubusercontent.com/z-shell/src/main/public/zsh/init.zsh