---
title: ⚡️ Installation
description: Installation Guide
canonical_url: https://wiki.zshell.dev/docs/getting_started/installation
markdown_url: https://wiki.zshell.dev/docs/getting_started/installation/index.md
locale: en
source_path: docs/getting_started/01_installation.mdx
---

<!-- Generated from the canonical Z-Shell Wiki build. The linked human-facing page remains the editorial source of truth. -->

# ⚡️ Installation

<a id="automated-setup"></a>

## Automated setup

tip

-   Verify the sha256 [checksum](https://raw.githubusercontent.com/z-shell/src/main/public/checksum.txt) for file: <kbd>lib/sh/install.sh</kbd>
-   If required append <kbd>-b &lt;tag&gt;</kbd> or <kbd>-b &lt;branch&gt;</kbd> e.g:

```sh
sh -c "$(curl -fsSL get.zshell.dev)" -- -i skip -b main
```

-   Minimal
-   Loader
-   Repository
-   Annex
-   ZUnit

Install and include minimal configuration to the <kbd>.zshrc</kbd>:

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

Install and include minimal configuration with [loader](#loader):

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

The installer will download the loader and add the snippet below to the <kbd>.zshrc</kbd> file.

```zsh
if [[ -n ${XDG_CONFIG_HOME:-} && $XDG_CONFIG_HOME == /* ]]; then
  ZI_LOADER_CONFIG_HOME="$XDG_CONFIG_HOME/zi"
else
  ZI_LOADER_CONFIG_HOME="$HOME/.config/zi"
fi
if [[ -r "$ZI_LOADER_CONFIG_HOME/init.zsh" ]]; then
  source "$ZI_LOADER_CONFIG_HOME/init.zsh" && zzinit
fi
unset ZI_LOADER_CONFIG_HOME
```

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

Clone repository using default or if set [custom](https://wiki.zshell.dev/docs/guides/customization/index.md#customizing-paths) values:

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

Install and include minimal configuration with recommended [annexes](https://wiki.zshell.dev/ecosystem/annexes/overview/index.md):

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

Install and include minimal configuration with recommended [annexes](https://wiki.zshell.dev/ecosystem/annexes/overview/index.md) and setup [z-shell/zunit](https://github.com/z-shell/zunit):

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

<a id="manual-setup"></a>

## Manual Setup

Related

-   [🏗 Configuration management](https://wiki.zshell.dev/docs/guides/customization/index.md#customizing-paths)

<a id="i-classfas-fa-spinner-fa-spini-prepare"></a>

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

```zsh
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 <kbd>compaudit</kbd> to check if the [completion system](https://zsh.sourceforge.io/Doc/Release/Completion-System.html#Use-of-compinit) would use files owned by <kbd>root</kbd> or by the current <kbd>user</kbd>, or files in directories that are <kbd>world</kbd> or <kbd>group-writable</kbd>.

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

```zsh
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]}"
```

<a id="i-classfas-fa-spinner-fa-spini-enable"></a>

### Enable

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

~/.zshrc

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

<a id="enable-zi-completions"></a>

### Completions

Enable Zi completions by placing the following snippet in the <kbd>.zshrc</kbd> file:

caution

The snippet below must be placed after after enabling Zi.

~/.zshrc

```zsh
autoload -Uz _zi
(( ${+_comps} )) && _comps[zi]=_zi
```

<a id="post-install"></a>

## Post-install

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

-   <kbd>exec zsh -il</kbd>
-   <kbd>zi self-update</kbd>

Run <kbd>zi -h</kbd> for available commands or [explore](https://wiki.zshell.dev/community/category/-collection) wiki to [extend](https://wiki.zshell.dev/ecosystem/index.md), [customize](https://wiki.zshell.dev/docs/guides/customization/index.md) and [create](https://wiki.zshell.dev/community/zsh_plugin_standard/index.md) 👍 🎉.

If you have any issue or need help 🤦‍♂️, lets [discuss](https://github.com/orgs/z-shell/discussions/new) it or open an [issue](https://github.com/z-shell/zi/issues/new/choose) on GitHub.

It helps us to improve and make Zi better. Don't forget to help the project: share, contribute, or [translate](https://digitalclouds.crowdin.com/z-shell) 🌐 🥰 🤓.

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

<a id="i-classfas-fa-sync-alt-fa-spini-have-ideas"></a>

## Have ideas?

<a id="suggest-or-request-at-playground"></a>

### Suggest or request at [playground](https://github.com/z-shell/playground)

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

<a id="i-classfas-fa-sync-alt-fa-spininbspneed-warm-up"></a>

## Need warm-up?

<a id="docker-alpine"></a>

### [Docker Alpine](https://github.com/z-shell/zd/pkgs/container/zd)

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

<a id="i-classfa-brands-fa-dockeri-turbo-zi-in-docker"></a>

### Turbo Zi in Docker

If you create a Docker image that uses Zi, install Turbo-loaded plugins before the shell starts interactively, with the <kbd>@zi-scheduler</kbd> 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 <kbd>wait</kbd> argument.

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

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

> -   An example: [Dockerfile](https://github.com/robobenklein/configs/blob/master/Dockerfile)
> -   In action: [Playground](https://github.com/z-shell/playground)

<a id="zi-module"></a>

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

-   [⚙️ Wiki: zpmod](https://wiki.zshell.dev/ecosystem/plugins/zsh-modules/index.md#i-classfa-brands-fa-githubi-z-shellzpmodzpmod-repo)
    
-   [📦 Source: zpmod](https://github.com/z-shell/zpmod)
    

<a id="available-links"></a>

## Available links

[Status page](https://status.zshell.dev/) ✅

<a id="installer"></a>

### Installer

<table><thead><tr><th>Service</th><th>URL</th></tr></thead><tbody><tr><td>Short URL</td><td><a href="https://get.zshell.dev/">https://get.zshell.dev</a></td></tr><tr><td>GitHub RAW</td><td><a href="https://raw.githubusercontent.com/z-shell/src/main/public/sh/install.sh">https://raw.githubusercontent.com/z-shell/src/main/public/sh/install.sh</a></td></tr></tbody></table>

<a id="loader"></a>

### Loader

<table><thead><tr><th>Service</th><th>URL</th></tr></thead><tbody><tr><td>Short URL</td><td><a href="https://init.zshell.dev/">https://init.zshell.dev</a></td></tr><tr><td>GitHub RAW</td><td><a href="https://raw.githubusercontent.com/z-shell/src/main/public/zsh/init.zsh">https://raw.githubusercontent.com/z-shell/src/main/public/zsh/init.zsh</a></td></tr></tbody></table>