https://github.com/zillowe/zoi
Advanced Package Manager & Environment Orchestrator
https://github.com/zillowe/zoi
developer-tools hacktoberfest package-manager rust zillowe zoi
Last synced: about 6 hours ago
JSON representation
Advanced Package Manager & Environment Orchestrator
- Host: GitHub
- URL: https://github.com/zillowe/zoi
- Owner: zillowe
- License: apache-2.0
- Created: 2025-07-22T09:49:34.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-07-07T21:10:23.000Z (3 days ago)
- Last Synced: 2026-07-07T23:06:58.470Z (3 days ago)
- Topics: developer-tools, hacktoberfest, package-manager, rust, zillowe, zoi
- Language: Rust
- Homepage: https://zillowe.qzz.io/docs/zds/zoi
- Size: 4.87 MB
- Stars: 69
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
Advanced Package Manager & Environment Orchestrator
%22&replace=v%241&style=flat&logo=homebrew&logoColor=%23ffff&label=Homebrew&labelColor=%235452f1&color=%23282696)
Docs •
Discord •
Security •
Contributing •
Changelog
Report a Bug •
Request a Feature •
Request an Enhancement
Code of Conduct •
Packaging •
Release Guidelines
Table of Contents
- [Features](#-features)
- [Special Thanks](#-special-thanks)
- [Getting Started](#-getting-started)
- [Zoi Mini](#zoi-mini)
- [Quick Start (Zero-Install)](#quick-start-zero-install)
- [Installation](#-installation)
- [Package Managers](#package-managers)
- [Scripts](#-scripts)
- [Linux](#linux)
- [Arch Linux (AUR)](#arch-linux-aur)
- [Fedora](#fedora)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [Windows](#windows)
- [Scoop](#scoop)
- [Crates.io](#cratesio)
- [NPM](#npm)
- [Build from Source](#-build-from-source)
- [Usage](#-usage)
- [Packaging Status](#-packaging-status)
- [Repositories & Mirrors](#-repositories--mirrors)
- [Contributing](#-contributing)
- [License](#-license)
Zoi is an advanced package manager and environment orchestrator, designed to simplify package management and environment configuration across multiple operating systems.
## Features
- **Cross-Platform:** Works seamlessly on Linux, macOS, and Windows.
- **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.
- **Extensive Dependency Management:** Integrates with over 40 system and language package managers (`apt`, `brew`, `cargo`, `npm`, `pip`, `go`, `bun`, etc.).
- **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.yaml` file.
- **Repository-Based:** Use official, community, or your own private/public Git-based repositories. Manage multiple registries.
- **Parallel Registry Sync:** Concurrently sync multiple package registries for significantly faster updates.
- **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.yaml` files 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 history` command.
- **Enhanced File Conflict Detection:** Prevents packages from accidentally overwriting existing files. Supports pre-download conflict checking via remote metadata to save bandwidth.
- **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`, `install`) to streamline creating and testing packages locally.
- **Advanced CLI Tools:**
- `zoi search`: Interactive TUI mode with result sorting and rich metadata.
- `zoi audit`: Scan installed packages for known security vulnerabilities.
- `zoi history`: Read the persistent audit trail of past transactions.
- `zoi doctor`: Proactive system health checks, including orphaned package detection and broken symlink scanning.
- `zoi man`: Read package manuals in the terminal.
- `zoi why`: Understand why a package is installed.
- `zoi rollback`: Revert a package to its previous version or rollback the entire last transaction.
- `zoi pin`: Pin a package to a specific version.
- `zoi exec`: Run a package's binary without installing it.
- `zoi shell -p`: Enter a temporary shell with a package available in PATH.
- **Zoi Mini:** A lightweight, zero-sync version for quick, one-off installations via `zm.sh` or `zm.ps1`. Supports `install`, `update`, `uninstall`, and `list` commands.
- **Library Support:** Core functionality is available as a Rust library to be integrated into other applications.
## Special Thanks
Thanks you all for helping with developing Zoi.
- [GitLab](https://gitlab.com): For offering their Ultimate plan for OSS projects.
- [Cloudflare](https://cloudflare.com): For offering their Pro plan through [Project Alexandria](https://www.cloudflare.com/lp/project-alexandria).
## Getting Started
Getting started with Zoi is simple. Just follow these three steps:
1. **Install Zoi:**
Choose one of the [installation methods](#-installation) below.
2. **Sync Repositories:**
Before you can install packages, you need to sync the package repositories.
```sh
zoi sync
```
3. **Install a Package:**
Now you can install any package you want. For example, to install `hello`:
```sh
zoi install @zillowe/hello
```
### 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 supports basic 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 :**
```sh
curl -fsSL https://zillowe.pages.dev/zm.sh | sh -s -- i @zillowe/hello
```
**Windows (amd64):**
```powershell
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 :**
```sh
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](https://zillowe.qzz.io/docs/zds/zsm).
```sh
curl -fsSL https://zillowe.pages.dev/scripts/zoi/install.zsm | zsm
```
**Windows:**
```powershell
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`](https://aur.archlinux.org/packages/zoi-bin) (Pre-compiled binary) or [`zoi`](https://aur.archlinux.org/packages/zoi) (built from source) from the AUR using your favorite helper (e.g. `yay`, `paru`):
```sh
yay -S zoi-bin
```
Or manually without any helpers:
```sh
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](https://gitlab.com/zillowe/zillwen/zusty/zoi/-/releases) and install it using `apt` or `dpkg`:
```sh
# 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](https://gitlab.com/zillowe/zillwen/zusty/zoi/-/releases) and install it using `dnf` or `rpm`:
```sh
# Using dnf (recommended)
sudo dnf install ./zoi-*.rpm
# Using rpm
sudo rpm -i zoi-*.rpm
```
##### Fedora (COPR)
Install `zoi` from Fedora [COPR](https://copr.fedorainfracloud.org/coprs/zillowez/zoi/) (Supports Fedora 43, 44, Rawhide, CentOS Stream 9/10, EPEL 9, and openSUSE Tumbleweed):
```sh
sudo dnf copr enable zillowez/zoi
sudo dnf install zoi
```
##### Fedora (Terra)
Install `zoi-rs` on Fedora from [Terra](https://terra.fyralabs.com) repo (not maintained by us so updates can be late, uses [Crates.io](#cratesio) version):
```sh
# 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](https://developer.fyralabs.com/terra/installing).
#### macOS
Install Zoi on macOS.
##### Homebrew
Install Zoi using Homebrew (Also supports linux):
```sh
brew install zillowe/tap/zoi
```
#### Windows
Install Zoi on Windows.
##### Scoop
Install Zoi using Scoop:
```powershell
scoop bucket add zillowe https://github.com/zillowe/scoop.git
scoop install zoi
```
#### Crates.io
You can install `zoi` directly from [crates.io](https://crates.io/crates/zoi-rs) using `cargo`:
```sh
cargo install zoi-rs
```
#### NPM
You can install `@zillowe/zoi` from `npm` also.
```sh
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](https://www.rust-lang.org) installed.
**Build the release binary:**
```sh
# For Linux/macOS
./scripts/build-release.sh
# For Windows
./scripts/build-release.ps1
```
**Install it locally:**
```sh
./configure
just build
sudo just install
```
Zoi integrates with over 40 system and language package managers (`apt`, `brew`, `cargo`, `npm`, `pip`, `go`, `bun`, and many more). See the full list on the [Dependencies docs](https://zillowe.qzz.io/docs/zds/zoi/dependencies).
## Usage
Here are some common commands to get you started.
- **Install a package:**
```sh
zoi install
```
- **Uninstall a package:**
```sh
zoi uninstall
```
- **Update packages:**
```sh
# Update all installed packages
zoi update --all
# Update specific packages
zoi update
```
- **Search for a package:**
```sh
# Standard search
zoi search
# Interactive TUI mode
zoi search -i
```
- **View operation history:**
```sh
zoi history
```
- **Show package details:**
```sh
zoi show
```
- **Run a project command:**
```sh
# Run a command defined in zoi.yaml
zoi run
```
- **Run a command without installing the package:**
```sh
zoi exec --
```
- **Enter a shell with a package:**
```sh
zoi shell -p
```
- **Add a new repository:**
```sh
# Interactively
zoi repo add
# By name from the default registry
zoi repo add
# From a git repo URL
zoi repo add https://github.com//.git
```
- **Update Zoi to the latest version:**
```sh
zoi upgrade
```
For more detailed information, please refer to the [Docs](https://zillowe.qzz.io/docs/zds/zoi).
## Packaging Status
[](https://repology.org/project/zoi/versions)
## Contributing
We welcome contributions from the community! If you'd like to contribute, please read our [Contributing Guidelines](./CONTRIBUTING.md) 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 (this repo)
- Primary: [GitLab](https://gitlab.com/zillowe/zillwen/zusty/zoi)
- Mirrors: [GitHub](https://github.com/zillowe/zoi), [Codeberg](https://codeberg.org/Zillowe/Zoi)
- Packages Database ([Zoidberg](https://zillowe.qzz.io/docs/zds/zoi/zoidberg))
- Primary: [GitLab](https://gitlab.com/zillowe/zillwen/zusty/zoidberg)
- Mirrors: [GitHub](https://github.com/zillowe/zoidberg), [Codeberg](https://codeberg.org/Zillowe/Zoidberg)
### Repository tiers
Repository tiers for [Zoidberg](https://gitlab.com/zillowe/zillwen/zusty/zoidberg), Zoi's official packages repo.
- Core: Essential packages, libraries and very common/maintained packages.
- Main: Packages that don't fit in Core but are essential for most people.
- Extra: Packages that are new, not very common or maintained, not preferable.
- Community: User submitted packages that are new, can be upgraded to a higher repo.
- Test: Testing repo for new Zoi features and for new packages before release.
- Archive: Archived packages that are no longer maintained.
- Zillowe: Zillowe's own official packages.
For details and CLI usage examples, see the docs page: [Repositories](https://zillowe.qzz.io/docs/zds/zoi/repositories).
## License
Zoi is licensed under the [Apache 2.0 License](./LICENSE).