Zoi

Introduction

Zoi is an advanced package manager and environment orchestrator, designed to simplify package management and environment configuration across multiple operating systems. It's part of the Zillowe Development Suite (ZDS) and aims to streamline your development workflow by managing tools and project environments with ease.

Features

• Cross-Platform: Works seamlessly on Linux, macOS, and Windows.
• Just-in-Time Privilege Escalation: Automatically prompts for sudo only when system-wide operations are required, keeping your environment and caches cleanly in user-space.
• Dynamic Package Definitions: Define packages with dynamic Lua scripts (.pkg.lua) for maximum flexibility.
• Universal Package Support: Install packages from pre-built binaries, compressed archives, or build them from source.
• ZoiOS Distro Engine: Bootstrap and manage entire Linux distributions declaratively. Includes generational rollbacks and transactional FHS views.
• Extensive Dependency Management: Integrates with over 40 system and language package managers (apt, brew, cargo, npm, pip, go, bun, etc.).
• Version Multiplexing via Intelligent Shims: Automatically switch between different versions of the same tool (e.g. Node.js 18 vs 20) based on your project context (zoi.lua) or legacy configuration files (.nvmrc) through its extensible Lua plugin system.
• Rich Dependencies: Define runtime and build dependencies with required, optional, and selectable options.
• Project Environments: Manage project tools with zoi.lua and named tasks with zoi.yaml.
• Repository-Based: Use official, community, or your own private/public Git-based repositories. Manage multiple registries.
• Secure & Verifiable: Verifies package integrity with checksums and authenticity with GPG signatures. Includes a built-in PGP key manager and handles configuration file updates safely.
• Advanced Dependencies: Supports virtual packages (provides) and package replacement (replaces).
• Versatile Package Types: Supports different types of packages:
  • Package: A standard software package.
  • Collection: A meta-package that groups other packages together.
  • App: A template for bootstrapping new projects (zoi create).
  • Extension: A package to extend Zoi's own functionality or configuration.
• Local Package Development: A dedicated zoi package command set (build, bundle, install, doctor, init-lsp) to streamline creating, linting, and testing packages locally.
• Advanced CLI Tools:
  • zoi man: Read package manuals in the terminal.
  • zoi audit: Scan installed packages for known security vulnerabilities.
  • zoi clone: Clone a package's git repository.
  • zoi download: Download a package archive (.zpa) or source bundle (.zsa).
  • zoi why: Understand why a package is installed.
  • zoi rollback: Revert a package to its previous version or roll back the newest remaining transaction log.
  • zoi pin: Pin a package to a specific version.
  • zoi exec: Run a package's binary without installing it.
  • zoi dev: Enter a project-specific development shell with all dependencies.
• Zoi Mini: A lightweight, zero-sync version for quick, one-off installations via zm.sh or zm.ps1.
• Library Support: Core functionality is available as a Rust library to be integrated into other applications.

Getting Started

For the fastest path through installation, registry sync, package installation, project environments, and first package creation, start with the Quick Start guide.

The minimal flow is three steps:

1. Install Zoi: Choose one of the installation methods below.

2. Sync Repositories: Before you can install packages, you need to sync the package repositories.

   zoi sync

3. Install a Package: Now you can install any package you want. For example, to install hello:

   zoi install @zillowe/hello

Common Workflows

Quick snippets for common tasks.

Setting up a new project

mkdir my-app && cd my-app
zoi use node@20 rust     # Add and install tools
zoi dev                  # Enter environment

Finding a command

zoi provides magick               # Finds 'imagemagick'
zoi provides libssl.so.3          # Finds 'openssl'

Cloning a package source

zoi clone @zillowe/hello          # Clones into 'hello' directory
zoi clone @zillowe/hello .        # Clones into current directory

Debugging dependencies

zoi tree @core/linux              # View full graph
zoi why openssl                   # See what requires it

Safe Upgrades

zoi update --all --dry-run        # See what will change
zoi update --all                  # Apply changes
zoi rollback --last-transaction   # Undo if broken

Building a Distribution (ZoiOS)

# Bootstrap ZoiOS onto a new disk or directory
sudo zoi system distro build --target /mnt --config ./system.lua

# Enter chroot and manage system generations
sudo zoi system apply
sudo zoi system rollback 42

Forcing a source build

zoi install --build --type source htop # Force rebuild from source

Zoi Mini

Zoi Mini is a lightweight, zero-sync version of Zoi that allows you to install packages from the official Zoidberg registry without installing the full Zoi suite. It's designed for quick, one-off installations and as-a-service scenarios. It supports basic package management commands: install, update, uninstall, and list.

Quick Start (Zero-Install)

You can install any package from the Zoidberg registry using a single command:

Linux / macOS :

curl -fsSL https://zillowe.pages.dev/zm.sh | sh -s -- i @zillowe/hello

Windows (amd64):

powershell -c "irm zillowe.pages.dev/zm.ps1 | iex" -args "i @zillowe/hello"

This will download the zoi-mini binary to a temporary location, resolve the package metadata dynamically, and perform the installation.

Installation

You can install Zoi using a package manager, an installer script, or by building it from source.

Scripts

You can also use our installer scripts for a quick setup.

Linux / macOS :

curl -fsSL https://zillowe.pages.dev/scripts/zoi/install.sh | bash

Or if you want a truly safe way to run this script use ZSM.

curl -fsSL https://zillowe.pages.dev/scripts/zoi/install.zsm | zsm

Windows:

powershell -c "irm zillowe.pages.dev/scripts/zoi/install.ps1|iex"

Package Managers

Linux

Install Zoi on Linux distros.

Arch Linux (AUR)

Install zoi-bin (Pre-compiled binary) or zoi (built from source) from the AUR using your favorite helper (e.g. yay, paru):

yay -S zoi-bin

Or manually without any helpers:

git clone https://aur.archlinux.org/zoi-bin.git
cd zoi-bin
makepkg -si

Debian / Ubuntu (.deb)

Download the .deb package for your architecture from the latest release and install it using apt or dpkg:

# Using apt (recommended, handles dependencies)
sudo apt install ./zoi-*.deb

# Using dpkg
sudo dpkg -i zoi-*.deb

Fedora / RHEL (.rpm)

Download the .rpm package for your architecture from the latest release and install it using dnf or rpm:

# Using dnf (recommended)
sudo dnf install ./zoi-*.rpm

# Using rpm
sudo rpm -i zoi-*.rpm

Fedora (COPR)

Install zoi from Fedora COPR (Supports Fedora 43, 44, Rawhide, CentOS Stream 9/10, EPEL 9, and openSUSE Tumbleweed):

sudo dnf copr enable zillowez/zoi
sudo dnf install zoi

Fedora (Terra)

Install zoi-rs on Fedora from Terra repo (not maintained by us so updates can be late, uses Crates.io version):

# add terra repo
dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
# install Zoi
sudo dnf install zoi-rs

More information and instructions for using Terra are available here.

macOS

Install Zoi on macOS.

Homebrew

Install Zoi using Homebrew (Also supports linux):

brew install zillowe/tap/zoi

Windows

Install Zoi on Windows.

Scoop

Install Zoi using Scoop:

scoop bucket add zillowe https://github.com/zillowe/scoop.git
scoop install zoi

Crates.io

You can install zoi directly from crates.io using cargo:

cargo install zoi-rs

NPM

You can install @zillowe/zoi from npm also.

npx @zillowe/zoi

bunx @zillowe/zoi

pnpm dlx @zillowe/zoi

yarn dlx @zillowe/zoi

Build from Source

If you prefer, you can build Zoi from source. You'll need Rust installed.

Build the release binary:

# For Linux/macOS
./scripts/build-release.sh

# For Windows
./scripts/build-release.ps1

Install it locally:

./configure
just build
sudo just install

Dependencies Support

What dependency installation we support.

And many more.

For more dependencies and information please visit the Dependencies Page.

Some of the package manager are OS specific, so when a dependency is in that package manager it only installs it for that OS.

But some other package managers like npm, it installs the dependency if the package manager is available.

Usage

Here are some common commands to get you started.

• Install a package:

  zoi install <package_name>

• Uninstall a package:

  zoi uninstall <package_name>

• Update packages:

  # Update all installed packages
  zoi update --all
  
  # Update specific packages
  zoi update <package1> <package2>

• Search for a package:

  zoi search <term>

• Show package details:

  zoi show <package_name>

• Run a project command:

  # Run a command defined in zoi.yaml
  zoi run <command_alias>

• Enter a development shell:

  # Enter a subshell with project dependencies available
  zoi dev

• Add a new repository:

  # Interactively
  zoi repo add
  
  # By name from the default registry
  zoi repo add <repo_name>
  
  # From a git repo URL
  zoi repo add https://github.com/<user_name>/<repo_name>.git

• Update Zoi to the latest version:

  zoi upgrade

See the full list of features.

Guides

To learn how to use Zoi in more advanced scenarios see guides.

Contributing

We welcome contributions from the community! If you'd like to contribute, please read our Contributing Guidelines for more information.

New features, enhancements and bug reports are welcome.

Repositories & Mirrors

Zoi is hosted on multiple forges. The primary locations and mirrors are:

• Zoi Source Code

  • Primary: GitLab
  • Mirrors: GitHub, Codeberg

• Packages Database (Zoidberg)

  • Primary: GitLab
  • Mirrors: GitHub, Codeberg

FAQ