# Zoi

**Repository Path**: iloverust/Zoi

## Basic Information

- **Project Name**: Zoi
- **Description**: 跨平台包管理器
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-25
- **Last Updated**: 2025-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
    <img width="120" height="120" hspace="10" alt="ZDS Logo" src="https://gitlab.com/Zillowe/Zillwen/Zusty/ZDS/-/raw/main/img/zds.png"/>
    <h1>Zoi</h1>
    <p><strong>Universal Package Manager & Environment Setup Tool</strong></p>
</div>

<br/>

<div align="center">
  <a href="https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/releases">
    <img alt="GitLab Latest Release" src="https://img.shields.io/gitlab/v/release/Zillowe%2FZillwen%2FZusty%2FZoi?sort=date&display_name=release&style=flat&logo=gitlab&logoColor=%23fff&label=Release&labelColor=%235452f1&color=%23282696"/>
  </a>
  <a href="https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/pipelines">
    <img alt="GitLab Pipeline Status" src="https://img.shields.io/gitlab/pipeline-status/Zillowe%2FZillwen%2FZusty%2FZoi?style=flat&logo=gitlab&logoColor=%23fff&label=Pipeline&labelColor=%235452f1"/>
  </a>
  <br/>
  <a href="https://aur.archlinux.org/packages/zoi-bin">
    <img alt="AUR Version" src="https://img.shields.io/aur/version/zoi-bin?style=flat&logo=archlinux&logoColor=%23ffff&label=AUR&labelColor=5452f1&color=282696"/>
  </a>
  <a href="https://github.com/Zillowe/homebrew-tap">
  <img alt="Homebrew Version" src="https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fraw.githubusercontent.com%2FZillowe%2Fhomebrew-tap%2Frefs%2Fheads%2Fmain%2Fzoi.rb&search=version%5Cs%2B%22(%5B%5E%22%5D%2B)%22&replace=%241&style=flat&logo=homebrew&logoColor=%23ffff&label=Homebrew&labelColor=%235452f1&color=%23282696">
  </a>
  <a href="https://github.com/Zillowe/scoop">
    <img alt="Scoop Version" src="https://img.shields.io/scoop/v/zoi?bucket=https%3A%2F%2Fgithub.com%2FZillowe%2Fscoop&style=flat&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj4NCjwhLS0gVXBsb2FkZWQgdG86IFNWRyBSZXBvLCB3d3cuc3ZncmVwby5jb20sIFRyYW5zZm9ybWVkIGJ5OiBTVkcgUmVwbyBNaXhlciBUb29scyAtLT4KPHN2ZyB3aWR0aD0iODAwcHgiIGhlaWdodD0iODAwcHgiIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiBmaWxsPSIjZmZmZmZmIj4KDTxnIGlkPSJTVkdSZXBvX2JnQ2FycmllciIgc3Ryb2tlLXdpZHRoPSIwIi8%2BCg08ZyBpZD0iU1ZHUmVwb190cmFjZXJDYXJyaWVyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz4KDTxnIGlkPSJTVkdSZXBvX2ljb25DYXJyaWVyIj4gPHRpdGxlPm1pY3Jvc29mdDwvdGl0bGU%2BIDxyZWN0IHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgZmlsbD0ibm9uZSIvPiA8cGF0aCBkPSJNMiwzaDl2OUgyVjNtOSwxOUgyVjEzaDl2OU0yMSwzdjlIMTJWM2g5bTAsMTlIMTJWMTNoOVoiLz4gPC9nPgoNPC9zdmc%2B&logoColor=%23ffff&label=Scoop&labelColor=%235452f1&color=%23282696"/>
  </a>
  <br/>
  <a href="https://crates.io/crates/zoi-rs">
    <img alt="Crates.io Version" src="https://img.shields.io/crates/v/zoi-rs?style=flat&logo=rust&logoColor=%23ffff&label=Crates.io&labelColor=%235452f1&color=%23282696">
  </a>
</div>

<br/>

<div align="center">
  <a href="https://zillowe.qzz.io/docs/zds/zoi"><strong>Docs</strong></a> •
  <a href="https://discord.gg/P4R7yaA3hf"><strong>Discord</strong></a> •
  <a href="./SECURITY.md"><strong>Security</strong></a> •
  <a href="./CONTRIBUTING.md"><strong>Contributing</strong></a> •
  <a href="./CHANGELOG.md"><strong>Changelog</strong></a>
  <br/>
  <a href="https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/issues/new?issuable_template=Bug%20Report"><strong>Report a Bug</strong></a> •
  <a href="https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/issues/new?issuable_template=Feature%20Request"><strong>Request a Feature</strong></a> •
  <a href="https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/issues/new?issuable_template=Enhancement%20Request"><strong>Request an Enhancement</strong></a>
  <br/>
  <a href="./CODE_OF_CONDUCT.md"><strong>Code of Conduct</strong></a> •
  <a href="./PACKAGING.md"><strong>Packaging</strong></a> •
  <a href="./RELEASE.md"><strong>Release Guidelines</strong></a>
</div>

<br/>
<hr/>
<br/>

<details>
<summary>Table of Contents</summary>

- [Features](#-features)
- [Getting Started](#-getting-started)
- [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](#%EF%B8%8F-build-from-source)
- [Platforms](#-platforms)
- [Dependencies Support](#-dependencies-support)
- [Usage](#-usage)
- [Packaging Status](#-packaging-status)
- [Repositories & Mirrors](#-repositories-mirrors)
- [Contributing](#-contributing)
- [License](#-license)

</details>

Zoi is a universal package manager and environment setup tool, 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 from binaries, compressed archives, source, or installer scripts.
- **Extensive Dependency Management:** Integrates with over 40 package managers (`apt`, `brew`, `cargo`, `npm`, `pip`, etc.).
- **Rich Dependencies:** Define runtime and build dependencies with required, optional, and selectable options.
- **Project Environments:** Manage project-specific commands and environments with `zoi.yaml`.
- **Repository-Based:** Use official, community, or your own private/public Git-based repositories.
- **Secure & Verifiable:** Verifies package integrity and authenticity with checksums and GPG signatures. Manage keys with `zoi pgp`.
- **Versatile Package Types:** Supports standard packages, collections, services, configs, app templates, extensions, libraries, and inline scripts.
- **Local Package Development:** A dedicated `zoi package` command set (`meta`, `build`, `install`) to streamline creating and testing packages locally.
- **Advanced CLI Tools:**
  - `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.
  - `zoi pin`: Pin a package to a specific version.
  - `zoi exec`: Run a package without installing it.
- **Library Support:** Use as a Rust library and get compiler/linker flags via `zoi pkg-config`.

## 🚀 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 hello
   ```

## 📦 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
```

**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
```

##### Fedora

Install `zoi-rs` on Fedora from [Terra](https://terra.fyralabs.com) repo (not maintained by us, uses [Crates.io](#cratesio) so may not be up-to-date):

```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
make build
sudo make install
# (optional) Install CLI completions and setup Zoi's PATH
make setup
```

## 💻 Platforms

What platforms we currently support.

| OS      | Arch  | Zoi Binary | Packages Support |
| ------- | ----- | ---------- | ---------------- |
| Linux   | amd64 | ✔️         | ✔️               |
| Linux   | arm64 | ✔️         | ✔️               |
| macOS   | arm64 | ✔️         | ✔️               |
| macOS   | amd64 | ✔️         | ✔️               |
| Windows | amd64 | ✔️         | ✔️               |
| Windows | arm64 | ❌         | ✔️               |
| FreeBSD | amd64 | ❌         | ✔️               |
| FreeBSD | arm64 | ❌         | ✔️               |
| OpenBSD | amd64 | ❌         | ✔️               |
| OpenBSD | arm64 | ❌         | ✔️               |

We're planning to add support for more platforms.

## 🔗 Dependencies Support

What dependency installation we support.

| Manager          | Ecosystem / OS                  | Example                                                                         |
| ---------------- | ------------------------------- | ------------------------------------------------------------------------------- |
| `zoi`            | Zoi                             | `zoi:my-other-package`                                                          |
| `native`         | System's native package manager | `native:openssl`                                                                |
| `script`         | Script execution                | `script:website.com/install`                                                    |
| `apt`, `apt-get` | Debian, Ubuntu, etc.            | `apt:libssl-dev`                                                                |
| `pacman`         | Arch Linux                      | `pacman:base-devel`                                                             |
| `yay`, `paru`    | Arch Linux (AUR)                | `yay:google-chrome`                                                             |
| `aur`            | Arch Linux (AUR)                | `aur:visual-studio-code-bin`                                                    |
| `brew`           | macOS (Homebrew)                | `brew:node`                                                                     |
| `scoop`          | Windows                         | `scoop:git`                                                                     |
| `snap`           | Linux (Snapcraft)               | `snap:node`                                                                     |
| `flatpak`        | Linux (Flathub)                 | `flatpak:org.gimp.GIMP`                                                         |
| `pkg`            | FreeBSD                         | `pkg:git`                                                                       |
| `pkg_add`        | OpenBSD                         | `pkg_add:git`                                                                   |
| `cargo`          | Rust                            | `cargo:ripgrep`                                                                 |
| `cargo-binstall` | Rust (pre-compiled binaries)    | `cargo-binstall:ripgrep`                                                        |
| `go`             | Go                              | `go:golang.org/x/tools/cmd/goimports`                                           |
| `npm`            | Node.js                         | `npm:typescript`                                                                |
| `bun`            | Bun                             | `bun:elysia`                                                                    |
| `deno`           | Deno                            | `deno:npm-chalk` or `deno:jsr-@std/bytes` (the `-` instead of `:` is important) |
| `jsr`            | JavaScript Registry             | `jsr:@std/http`                                                                 |
| `pip`            | Python                          | `pip:requests`                                                                  |
| `nix`            | NixOS / Nix                     | `nix:nixpkgs.hello`                                                             |

And many more.

For more dependencies and information please visit the [Dependencies Page](https://zillowe.qzz.io/docs/zds/zoi/dependencies) on Docs.

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:**

  ```sh
  zoi install <package_name>
  ```

- **Uninstall a package:**

  ```sh
  zoi uninstall <package_name>
  ```

- **Install from a specific repository:**

  ```sh
  zoi install @<repo_name>/<package_name>
  ```

- **List all available packages from active repos:**

  ```sh
  zoi list --all
  ```

- **List packages from a specific repo:**

  ```sh
  zoi list --all --repo <repo_name>
  ```

- **Search for a package:**

  ```sh
  zoi search <term>
  ```

- **Search for a package from a specific repo:**

  ```sh
  zoi search <term> @<repo_name>
  ```

- **Add a new repository:**

  ```sh
  # Interactively
  zoi repo add

  # By name
  zoi repo add <repo_name>
  # From a git repo
  zoi repo add https://github.com/<user_name>/<repo_name>.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

[![Packaging status](https://repology.org/badge/vertical-allrepos/zoi.svg)](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)
  - 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).

<hr/>

<div align="center">
  <p>Zoi is developed by Zusty < Zillowe Foundation<br/>Part of the <a href="https://gitlab.com/Zillowe/Zillwen/Zusty/ZDS">Zillowe Development Suite (ZDS)</a></p>
</div>