Zoi
Advanced Package Manager & Environment Orchestrator.
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
sudoordoasonly 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. - ZoiOS Distro Engine: Bootstrap and manage entire Linux distributions declaratively.
- 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-specific commands and environments using a local
zoi.yamlor azoi.luafile. - Repository-Based: Use official, community, or your own private/public Git-based repositories.
- Secure & Verifiable: Verifies package integrity with checksums and authenticity with GPG signatures. Supports Git commit signature verification for entire registries (Chain of Trust) and includes a built-in PGP keyring for out-of-the-box security.
- Decentralized Security Advisories: Automated vulnerability tracking via
.sec.yamlfiles co-located with packages. Zoi proactively warns you during installation or upgrades if a package has known security issues. - Compliance & Audit Logging: Maintain a persistent, tamper-evident audit log of all package operations (install, uninstall, upgrade), viewable via the
zoi historycommand. - 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 packagecommand 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.shorzm.ps1. Supportsinstall,update,uninstall, andlistcommands. - 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:
-
Install Zoi: Choose one of the installation methods below.
-
Sync Repositories: Before you can install packages, you need to sync the package repositories.
zoi sync -
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 environmentFinding 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 directoryDebugging dependencies
zoi tree @core/linux # View full graph
zoi why openssl # See what requires itSafe Upgrades
zoi update --all --dry-run # See what will change
zoi update --all # Apply changes
zoi rollback --last-transaction # Undo if brokenForcing a source build
zoi install --build --type source htop # Force rebuild from sourceInstallation
You can install Zoi using a package manager, an installer script, or by building it from source.
Scripts
You can use our installer scripts for a quick setup.
Linux / macOS :
curl -fsSL https://zillowe.pages.dev/scripts/zoi/install.sh | bashOr if you want a truly safe way to run this script use ZSM.
curl -fsSL https://zillowe.pages.dev/scripts/zoi/install.zsm | zsmWindows:
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):
paru -S zoi-binOr manually without any helpers:
git clone https://aur.archlinux.org/zoi-bin.git
cd zoi-bin
makepkg -siDebian / 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-*.debFedora / 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-*.rpmOr you can 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 zoiOr you can install zoi-rs on Fedora from Terra repo:
# add terra repo
dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
# install Zoi
sudo dnf install zoi-rsMore 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/zoiWindows
Install Zoi on Windows.
Scoop
Install Zoi using Scoop:
scoop bucket add zillowe https://github.com/zillowe/scoop.git
scoop install zoiCrates.io
You can install zoi directly from crates.io using cargo:
cargo install zoi-rsNPM
You can install @zillowe/zoi from npm also.
npx @zillowe/zoi
bunx @zillowe/zoi
pnpm dlx @zillowe/zoi
yarn dlx @zillowe/zoiBuild from Source
If you prefer, you can build Zoi from source. You'll need Rust installed.
Build the release binary:
./configure
just buildInstall it locally:
sudo just installZoi 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/helloWindows (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.
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
-
Packages Database (Zoidberg)
FAQ
You can create a .pkg.lua file that defines your package. This file includes metadata like the package name, version, description, and installation instructions. For a complete guide, please visit the Creating Packages guide.
To learn how to publish a package to the official repositories or your own, please visit the Publishing Packages guide.
Use zoi man <package-name> to view it in your terminal. For uninstalled packages, Zoi will automatically fetch the manual from the registry.
You can add a new repository using the zoi repo add command. You can run it
without arguments for an interactive prompt, or provide the name of the
repository to add it directly.
Zoi is designed to be cross-platform. Mainly supports Linux, macOS and Windows, and amd64 and arm64 architectures.
Yes, Zoi supports installing dependencies from a wide range of other package
managers like brew, winget, scoop, npm, cargo, pip, and many more.
These are defined in the dependencies section of a packags's .pkg.lua
file.
You can append a version or channel after an '@' in the source string.
Examples: zoi install my-app@1.2.3 or use channels defined in versions
like my-app@stable. You can also pin a resolved version to prevent updates:
zoi pin my-app VERSION and later zoi unpin my-app.
Use zoi exec <package>. Zoi resolves the package and its dependencies
into an ephemeral environment and runs the binary directly. Use --bin
to specify which binary for multi-binary packages. Sandboxed packages
are automatically wrapped with bwrap.
zoi dev is used to enter a persistent development subshell. It automatically
ensures all packages in your zoi.yaml are installed locally and sets up
environment variables like PATH, LD_LIBRARY_PATH, and CPATH so you can
immediately start compiling or running your code. zoi env is more focused on
running specific setup scripts or one-off environment configurations.
Add it with zoi repo add https://github.com/you/your-zoi-repo.git.
Install packages from it using #git@<repo-name>/<pkg-name>.
List/remove cloned git repos with zoi repo git ls and
zoi repo git rm <repo-name>.
Binaries are placed in ~/.zoi/pkgs/store/<name>/bin and linked into
~/.zoi/pkgs/bin. Zoi attempts to add this to your shell PATH on Unix and user PATH on Windows.
If commands are not found, run zoi shell <shell> to configure your shell, or add ~/.zoi/pkgs/bin to your PATH manually.
Pass --yes to installation commands to auto-accept confirmations and
optional dependency prompts. To install all optional dependencies without
being prompted, use --all-optional.
Use the full path in the source, e.g. @core/linux/amd64/nvidia-driver.
Run zoi upgrade. You can use zoi upgrade --force to upgrade even if you are on the latest version, and zoi upgrade --tag <tag> or zoi upgrade --branch <branch> to target a specific release.
If an update causes issues, you can revert to the previously installed version using zoi rollback <package-name>. Zoi automatically creates a backup before upgrading a package.
Zoi automatically keeps a record of all your installed packages in a JSON file
at ~/.zoi/pkgs/zoi.lock. You can back up this file. To restore all your
packages on a new system, simply run zoi install /path/to/your/zoi.lock.
We believe in privacy by design. Zoi does not collect any data by default. You can choose to opt-in to our anonymous telemetry to help us improve the application. To learn more about what we collect and why, please see our Telemetry & Analytics page.
2026 © All Rights Reserved.
- All the content is available under CC BY-SA 4.0, expect where otherwise stated.
- Source code is available on GitLab, licensed under Apache 2.0.
Last updated on