---
title: Package guide
description: Learn how Zi packages work, choose installation profiles, update tools, and add a package definition.
canonical_url: https://wiki.zshell.dev/ecosystem/packages/guide
markdown_url: https://wiki.zshell.dev/ecosystem/packages/guide/index.md
locale: en
source_path: ecosystem/packages/01_guide.mdx
---

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

# Package guide

Zi packages bundle a software source and a set of [ice modifiers](https://wiki.zshell.dev/docs/guides/syntax/ice-modifiers/index.md) into a reusable installation recipe. Instead of repeating a long configuration, choose a package and a profile.

[Browse the package catalog](https://wiki.zshell.dev/ecosystem/packages/index.md) to find a tool and its installation commands.

<a id="before-you-start"></a>

## Before you start

Load [Zi](https://wiki.zshell.dev/docs/getting_started/installation/index.md) in Zsh before running package commands. Install the annexes and system tools required by the selected profile; the catalog lists these beside each package.

The [bin-gem-node](https://wiki.zshell.dev/ecosystem/annexes/bin-gem-node/index.md) annex provides Node and Gem installation support and executable shims. A shim forwards a command to a program installed inside a package directory. Some recipes instead add a directory to `PATH` or install into Zi's `$ZPFX` prefix.

<a id="introductory-example"></a>

## Install a package

For example, install the default `fzf` profile:

```zi
zi pack for fzf
```

The package definition supplies the download and build configuration. The current default profile builds from Git and needs Go and Make; the [fzf card](https://wiki.zshell.dev/ecosystem/packages/index.md#fzf) also offers a binary profile.

<a id="choose-a-profile"></a>

## Choose a profile

Every package has a `default` profile. Additional profiles can change the source, enable shell integration, or expose commands through shims:

```zi
zi pack"binary" for fzf
```

Profiles are package-specific. Use the names shown in that package's card rather than assuming that every package supports `binary`, `bgn`, or the same version numbers.

You can override an individual ice modifier alongside `pack`, but first check the package definition: its installation and update hooks may rely on each other.

Package names that collide with an ice-modifier prefix need an `@` prefix, for example:

```zi
zi pack for @asciidoctor
```

<a id="the-any-gem-and-any-node-packages"></a>

## Install Node modules or Ruby gems

The [any-node](https://wiki.zshell.dev/ecosystem/packages/index.md#any-node) and [any-gem](https://wiki.zshell.dev/ecosystem/packages/index.md#any-gem) packages accept the module or gem name as a parameter. Their catalog cards include commands and current prerequisites.

When keeping such a command in `.zshrc`, give each installation a stable, distinct `id-as` value. Zi then identifies the installed package when the shell starts again.

<a id="update-and-remove-packages"></a>

## Update and remove packages

Use the installed package ID with Zi's usual commands. For the default `fzf` installation:

```zi
zi update fzf
```

Updating follows the recipe, so it may rebuild software or run installation hooks again. If you supplied `id-as`, use that ID instead of the recipe name.

To remove an installation:

```zi
zi delete fzf
```

Review the package's installation effects before removal. Files written outside its directory, including system-wide files, may need separate cleanup.

<a id="pros-of-using-the-zi-package-for-regular-software-installations"></a>

## Benefits and trade-offs

-   **Reusable setup:** the recipe carries its source, build steps, and shell integration in one place.
-   **Choice of installation:** profiles may offer source builds, binaries, or shims without duplicating the full ice list.
-   **Local installation:** many recipes install beneath your home directory. This is not universal: the default `zsh-bin` profile writes to `/usr/local` and attempts to register a login shell.
-   **Dependencies and maintenance:** packages can require compilers, external tools, or annexes. Recipes and upstream downloads can change independently; a package listing is not a guarantee that every platform or Zi branch is supported.
-   **Executable recipes:** install and update hooks run commands in your environment. Review the package repository before using a recipe or overriding its hooks.

<a id="adding-your-package"></a>

## Add a package

A Zi package repository contains a `package.json` with source metadata under `zsh-data.plugin-info` and named profiles under `zsh-data.zi-ices`. Start with a small existing definition such as [doctoc's package.json](https://github.com/z-shell/doctoc/blob/main/package.json).

1.  Describe the upstream software and its source in the package metadata.
2.  Define a `default` profile in `zi-ices`, using the same ice modifiers you would pass to Zi. Add other profiles only for supported alternatives.
3.  Declare required tools and annexes, and document platform limitations and installation effects.
4.  Validate installation, updates, and removal in an isolated environment before publishing the recipe.
5.  For discovery under the Z-Shell organization, coordinate with its maintainers. For another owner, see [`ZI[PKG_OWNER]`](https://wiki.zshell.dev/docs/guides/customization/index.md#modify-settings).

Use current `zi-ices` metadata when creating a package. Zi's current `main` reader accepts legacy `zplugin-ices` when `zi-ices` is absent, but the package contract and validator require `zi-ices` for new definitions.
